@RequestParam과 @PathVariable 사용법: Spring에서의 URL 파라미터 처리

@RequestParam과 @PathVariable은 Spring MVC에서 클라이언트 요청으로 전달된 값을 컨트롤러 메서드에 바인딩할 때 사용하는 핵심 어노테이션입니다. 특히 REST API 설계 시 이 둘의 차이와 사용법을 정확히 이해하고 있는 것이 중요합니다.

 

1. @RequestParam: 쿼리 스트링 파라미터 바인딩

@RequestParam은 ?key=value 형식의 쿼리 스트링 파라미터를 메서드 인자에 주입할 때 사용합니다.

예시

@GetMapping("/search")
public String search(@RequestParam String keyword, @RequestParam(defaultValue = "1") int page) {
    System.out.println("검색어: " + keyword);
    System.out.println("페이지: " + page);
    return "searchResult";
}

위 API에 대해 요청 예시:

GET /search?keyword=spring&page=2

특징:

• 필수 파라미터: required=true (기본값)
• 기본값 지정: defaultValue 속성으로 설정 가능
• 파라미터가 없을 경우 예외 발생 가능 (nullable이 아니면)

 

2. @PathVariable: 경로 변수 바인딩

@PathVariable은 URL 경로 일부를 변수처럼 사용할 때 사용합니다. RESTful API 설계에서 자주 활용됩니다.

예시

@GetMapping("/users/{userId}/posts/{postId}")
public String getPost(@PathVariable Long userId, @PathVariable Long postId) {
    System.out.println("유저 ID: " + userId);
    System.out.println("포스트 ID: " + postId);
    return "postDetail";
}

위 API에 대해 요청 예시:

GET /users/42/posts/1001

특징:

• 경로 변수 이름과 메서드 파라미터명이 다를 경우 @PathVariable("이름")으로 명시
• 필수 파라미터이므로 누락되면 400 에러 발생

 

3. @RequestParam vs @PathVariable 차이점 요약

구분	@RequestParam	@PathVariable
용도	쿼리 파라미터 (예: ?key=value)	URI 경로 일부
RESTful API	선택적 정보에 적합	리소스 식별자에 적합
기본값 설정	가능 (defaultValue)	불가
필수 여부	설정 가능 (required)	항상 필요

4. 실무 팁

• 리소스 식별자(ID)는 보통 @PathVariable로 처리하는 것이 RESTful 스타일에 맞습니다.
• 검색 조건, 정렬 기준, 페이지 번호 등은 @RequestParam으로 처리하는 것이 일반적입니다.
• Spring 4.3 이후부터는 파라미터 이름이 동일할 경우 value 속성 생략이 가능합니다.

 

결론

@RequestParam과 @PathVariable은 각각의 목적에 맞게 사용해야 클린한 API 설계가 가능합니다. 특히 RESTful 서비스에서는 경로 기반 리소스 식별과 쿼리 기반 필터링/옵션 분리를 명확히 해두는 것이 유지보수성과 직관성을 크게 향상시킵니다.