@PathVariable vs @RequestParam

@PathVariable

@Target(PARAMETER)
@Retention(RUNTIME)
@Documented
public @interface PathVariable

 

설명

---

@PathVariable은 메서드 파라미터가 URI 템플릿 변수에 바인딩되어야 함을 나타냅니다. @RequestMapping으로 정의된 핸들러 메서드에서 지원됩니다.

예를 들어 /users/{id} 같은 경로에서 id를 메서드 파라미터로 받기 위해 사용합니다.

만약 파라미터 타입이 Map<String, String>이라면, 모든 경로 변수 이름과 값을 자동으로 맵에 채웁니다.

 

사용 예시

---

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

 

@GetMapping("/users/{userId}/orders/{orderId}")
public ResponseEntity<Order> getOrder(
    @PathVariable String userId,
    @PathVariable String orderId
) {
    return orderService.findOrder(userId, orderId);
}

 

주요 속성

---

속성명	타입	설명
value	String	name의 별칭입니다. URI 템플릿 변수 이름 지정
name	String	바인딩할 경로 변수 이름 (Spring 4.3.3부터)
required	boolean	기본값은 true. URL에 값이 없으면 예외 발생. false로 설정하면 null이나 Optional 사용 가능

 

메타 정보

---

• Since: Spring 3.0
• Author: Arjen Poutsma, Juergen Hoeller
• See also: @RequestMapping, RequestMappingHandlerAdapter

 

 

@RequestParam

---

@Target(PARAMETER)
@Retention(RUNTIME)
@Documented
public @interface RequestParam

설명

---

@RequestParam은 메서드 파라미터를 웹 요청의 파라미터에 바인딩하기 위한 어노테이션입니다.

Spring MVC와 Spring WebFlux 모두에서 지원되며, 동작 방식은 다음과 같습니다:

• Spring MVC: 쿼리 파라미터, form data, multipart 요청의 일부를 포함합니다. 이는 Servlet API가 모든 요청 데이터를 하나의 parameters 맵으로 합치기 때문입니다.
• Spring WebFlux: 쿼리 파라미터만을 매핑합니다. form/multipart data는 @ModelAttribute와 커맨드 객체를 통해 처리해야 합니다.

 

Map 활용

---

• 파라미터 타입이 Map이고 name이 지정된 경우 → 변환 전략을 통해 요청값을 Map으로 변환
• 파라미터 타입이 Map<String, String> 또는 MultiValueMap<String, String>이고 name이 생략된 경우 → 전체 요청 파라미터를 맵에 자동 주입

 

사용 예시

---

@GetMapping("/search")
public List<Product> search(@RequestParam String keyword) {
    return productService.search(keyword);
}

@GetMapping("/filter")
public String filter(@RequestParam Map<String, String> params) {
    return params.toString(); // 전체 쿼리 파라미터
}

 

주요 속성

---

속성명	타입	설명
value	String	name의 별칭
name	String	바인딩할 요청 파라미터 이름 (Spring 4.2부터)
required	boolean	기본값은 true. 파라미터가 없으면 예외 발생. false로 설정하면 null 허용
defaultValue	String	요청값이 없거나 빈 문자열일 경우 사용할 기본값. 설정 시 required는 자동으로 false 처리됨

 

메타 정보

---

• Since: Spring 2.5
• Author: Arjen Poutsma, Juergen Hoeller, Sam Brannen
• See also: @RequestMapping, @RequestHeader, @CookieValue

 

사용 이유

---

@RequestParam을 사용할 때

• 요청 파라미터가 선택적(optional)인 경우
• 파라미터가 다수인 경우 (예: 검색 조건, 정렬 기준, 필터링 등)
• URL 경로를 간결하게 유지하고 싶은 경우

 

@PathVariable을 사용할 때

• 파라미터가 필수(required)이며, 리소스를 식별하는 경우
• RESTful API에서 URL이 자원의 계층 구조를 명확하게 표현해야 하는 경우
• 예: /users/123, /posts/456/comments/789

 

비교

---

항목	@PathVariable	@RequestParam
바인딩 대상	URI 경로 템플릿 (/users/{id})	쿼리 파라미터 (/users?id=1)
URL 예시	/products/10	/products?id=10&name=pen
선택적 파라미터 가능?	required=false 설정 가능 (4.3.3+)	required=false, defaultValue 제공 가능
전체 매핑 가능 여부	Map<String, String> 가능	Map<String, String>, MultiValueMap 가능
주 사용 목적	리소스 식별자	필터, 검색, 옵션 지정 등

 

결론

---

• @PathVariable은 경로 자체에 포함된 값을 추출할 때 사용하며, RESTful URI 설계에 적합합니다.
• @RequestParam은 쿼리 파라미터를 다루며, 검색, 정렬, 필터링 같은 요청에 적합합니다.
• 두 어노테이션 모두 유연한 속성 설정이 가능하며, 복잡한 요청에도 대응할 수 있도록 다양한 조합이 가능합니다.