Java @PathVariable null 입력시 에러 처리

Java 기반의 Spring Framework를 사용하는 웹 애플리케이션에서 @PathVariable을 사용하여 URL 경로에서 파라미터를 매핑할 때, 종종 예상치 못하게 null 값이 전달되는 문제가 발생한다. 이는 개발 초기 단계에서는 간과되기 쉬우며, 실서비스에 돌입한 후 예외 처리를 어렵게 만들 수 있다. 이 글에서는 @PathVariable이 null로 입력되는 원인부터 시작하여, 실무에서 적용 가능한 해결 방안을 기술적으로 정리한다.

Spring MVC에서 @PathVariable의 작동 원리

경로 변수와 URI 템플릿의 관계

Spring은 @RequestMapping, @GetMapping 등과 함께 사용되는 URI 템플릿에서 경로 변수(Path Variable)를 추출하여 컨트롤러 메서드 파라미터에 자동 바인딩한다.

예시:

@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    ...
}

이때, 클라이언트가 /users/123 요청을 보냈다면 id 값으로 123이 바인딩된다. 하지만 다음과 같은 상황에서는 id가 null로 처리될 수 있다:

• URI 경로가 잘못 지정되었을 경우
• 경로 변수명이 메서드 파라미터와 일치하지 않을 경우
• Spring 버전 또는 설정 문제

매핑 실패 시 발생 가능한 현상

• 404 오류 반환
• @PathVariable에 null 전달
• HttpMessageNotReadableException 발생

반응형

@PathVariable이 null이 되는 주요 원인 분석

1. 경로 변수 이름 불일치

메서드의 @PathVariable 이름과 URI 경로의 변수 이름이 다르면, 자동 바인딩이 되지 않아 null이 반환된다.

// 잘못된 예
@GetMapping("/product/{id}")
public ResponseEntity<Product> getProduct(@PathVariable("productId") Long id) {
    ...
}

해결 방법:

@GetMapping("/product/{id}")
public ResponseEntity<Product> getProduct(@PathVariable("id") Long id) {
    ...
}

2. @PathVariable 이름 생략 문제 (기본 명명 일치 필요)

Spring 4.3 이후로는 @PathVariable의 이름을 생략할 수 있지만, 이 경우 파라미터 변수명이 URI의 경로 변수명과 일치해야 한다.

@GetMapping("/orders/{orderId}")
public ResponseEntity<Order> getOrder(@PathVariable Long orderId) {
    ...
}

주의: 파라미터 이름이 order_id 등으로 다르면 null 처리됨.

3. 선택적 PathVariable 사용 시 required=false 명시 누락

선택적으로 사용할 경우 required=false를 명시하지 않으면 필수값으로 인식하여 오류가 발생한다.

@GetMapping("/search/{keyword}")
public ResponseEntity<?> search(@PathVariable(required = false) String keyword) {
    ...
}

4. 요청 URI 자체의 누락 또는 오타

클라이언트 요청 URI가 /users처럼 {id} 부분이 없는 경우, 해당 경로에 대한 매핑이 없어 null 또는 404 에러 발생.

5. 컨트롤러의 클래스 레벨 매핑 미확인

@RestController
@RequestMapping("/api")
public class ProductController {

    @GetMapping("/items/{id}")
    public ResponseEntity<Item> getItem(@PathVariable Long id) {
        ...
    }
}

이 경우 요청 URI는 /api/items/123이어야 하고, /items/123만 보내면 매핑 실패로 @PathVariable이 null 처리됨.

핵심 키워드 강조: Java @PathVariable null 원인과 해결 방안 정리

반응형

실무에서 @PathVariable null 문제 방지 전략

1. 명시적으로 변수 이름 지정

혼동 방지를 위해 항상 변수 이름을 명시적으로 선언하는 것이 안전하다.

@GetMapping("/employees/{empId}")
public ResponseEntity<Employee> getEmployee(@PathVariable("empId") Long empId) {
    ...
}

2. required = false 옵션 활용

경로가 조건부일 수 있는 경우, @RequestParam과 혼용하거나 required = false로 처리하여 유연한 로직 구현이 가능하다.

@GetMapping(value = {"/files", "/files/{type}"})
public ResponseEntity<List<File>> listFiles(@PathVariable(required = false) String type) {
    ...
}

3. Swagger나 Spring REST Docs 활용하여 명세 점검

API 문서를 자동화하면 클라이언트와 서버 간의 계약을 명확히 하여 누락 또는 오타 방지 가능.

4. 테스트 코드 기반 검증 필수

경로 변수에 대한 단위 테스트 작성은 누락 및 오류 방지에 탁월하다.

mockMvc.perform(get("/users/1"))
       .andExpect(status().isOk())
       .andExpect(jsonPath("$.id").value(1));

5. PathPatternParser 설정 고려

Spring Boot 2.6 이상에서는 기본 URI 매핑이 PathPatternParser로 바뀌면서 이전 방식과 호환되지 않을 수 있다. application.properties에 다음 설정 추가 필요:

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

 

반응형

고급 사례

경로 중첩 상황 예시

@GetMapping("/projects/{projectId}/tasks/{taskId}")
public ResponseEntity<Task> getTask(@PathVariable Long projectId, @PathVariable Long taskId) {
    ...
}

이때 클라이언트는 /projects/10/tasks/5로 정확히 요청해야 하며, 중간에 경로가 누락되면 taskId가 null 처리되거나 404 에러 반환됨.

경로에 특수 문자 포함 시 인코딩 필수

특수 문자(공백, 슬래시 등)는 반드시 URI 인코딩 처리를 해야 경로 변수 추출이 가능하다.

URI uri = URI.create("/search/%EC%95%84%EC%9D%B4%ED%85%9C"); // 아이템 검색 시

 

반응형

결론

@PathVariable은 Spring 기반 REST API 개발의 핵심 기능이다. 하지만 이처럼 단순한 어노테이션도 경로 구조, 명명 불일치, 설정 오류 등으로 인해 예기치 않은 null 값 문제를 유발할 수 있다. 이를 방지하기 위해서는 명세 기반 개발, 정확한 테스트, URI 템플릿에 대한 깊은 이해가 요구된다. 본 가이드를 참고하여 @PathVariable 관련 오류를 미연에 방지하고, 안정적인 REST API를 설계하길 바란다.