@PathVariable은 URL 경로 자체에 포함된 값을 컨트롤러 메서드 파라미터로 바인딩해주는 Spring MVC 애노테이션입니다.
RESTful API 스타일에서 주로 사용되며,
/{id}, /{name}같은 경로 값을 가져올 때 사용합니다.
사용 목적
- 쿼리 스트링이 아닌 URL 경로 일부를 변수로 사용하고 싶을 때
- RESTful 설계에서 리소스 식별자(id 등)를 표현하고자 할 때
예시
GET /news/123흐름
1. 클라이언트가 경로 기반 요청 전송
- 클라이언트(브라우저, JS, Postman 등)는 다음과 같은 형태로 요청을 보냅니다.
GET /news/123- 이때 123은 URL 경로의 일부이며, 리소스를 식별하는 값(ID 등)입니다.
2. DispatcherServlet이 요청을 수신
- 스프링 부트 애플리케이션이 구동되면
DispatcherServlet이 모든 HTTP 요청을 먼저 가로챕니다. - web.xml 설정 없이 자동 등록됨(Spring Boot 자동 설정)
- 이 서블릿은 “프론트 컨트롤러(Front Controller)” 역할을 수행하며, 어떤 컨트롤러가 요청을 처리할지 결정합니다.
3. HandlerMapping이 요청 URI를 분석
DispatcherServlet은 등록된RequestMappingHandlerMapping에게 요청 URI(/news/123)와 일치하는 메서드가 있는지 묻습니다.- 예를 들어 다음과 같은 핸들러가 있다고 가정하면:
@GetMapping("/news/{id}")
public String getNews(@PathVariable("id") int id) { ... }HandlerMapping은 이 URI 템플릿/news/{id}와/news/123이 패턴 매칭으로 일치한다고 판단합니다.
4. HandlerAdapter가 해당 메서드 실행 준비
- 매핑된 컨트롤러 메서드를 실행하기 위해
RequestMappingHandlerAdapter가 선택됩니다. - 이 어댑터는 실제 메서드를 실행하기 전에, 각 파라미터에 어떤 값을 주입할지 분석합니다.
5. HandlerMethodArgumentResolver가 파라미터 분석
@PathVariable이 붙은 파라미터는PathVariableMethodArgumentResolver가 처리합니다.- 스프링 내부적으로 다음과 같은 처리를 합니다.
// 예시 URI: /news/123
// URI 템플릿: /news/{id}
Map<String, String> uriVariables = Map.of("id", "123");- 이 맵을 기준으로 파라미터 이름(id)에 해당하는 문자열 값을 찾아 바인딩합니다.
6. 타입 변환 수행
- 바인딩 대상 파라미터가
int, long, UUID등일 경우, 스프링은 내부의ConversionService를 사용하여 문자열 값을 자동으로 타입 변환합니다.
// 예시
int id = Integer.parseInt("123");- 변환이 실패하면
MethodArgumentTypeMismatchException예외가 발생하고400오류 반환
7. 변수 주입 후 컨트롤러 메서드 실행
- 모든 파라미터 바인딩이 끝나면 해당 컨트롤러 메서드가 실행됩니다.
@GetMapping("/news/{id}")
public String getNews(@PathVariable int id) {
// id = 123
...
}- 이후 메서드 리턴값에 따라 뷰 이름을 렌더링하거나, JSON 응답을 반환합니다 (
@ResponseBody, @RestController사용 시).
예제
1. 기본 사용
@GetMapping("/news/{id}")
public String viewNews(@PathVariable("id") int id, Model model) {
model.addAttribute("newsId", id);
return "newsDetail";
}GET /news/101- URL 경로에 포함된 숫자 101이 id 파라미터로 전달됨
@PathVariable("id")은{id}에 해당하는 값을 바인딩- 문자열 "101"은 자동으로 int 타입으로 변환됨
2. 변수명 일치 시 @PathVariable 값 생략 가능
@GetMapping("/user/{username}")
public String userProfile(@PathVariable String username) {
return "사용자 이름: " + username;
}GET /user/Daniel- URL의
{username}과 메서드 파라미터 이름이 같으면 "username" 생략 가능 - "Daniel"이 username 변수에 바인딩됨
- 타입이 String이므로 별도 변환 없이 바로 사용 가능
3. 여러 개의 PathVariable 처리
@GetMapping("/category/{categoryId}/item/{itemId}")
public String itemDetail(@PathVariable int categoryId,
@PathVariable int itemId) {
return "카테고리: " + categoryId + ", 아이템: " + itemId;
}GET /category/5/item/10- URL에 있는 두 개의 값 5와 10이 각각 categoryId, itemId에 매핑됨
- 다중
@PathVariable은 각{}이름과 파라미터를 정확히 매칭해야 함 - 문자열 "5", "10"은 각각 int 타입으로 자동 변환되어 메서드 실행됨
donggyun_ee