[Spring] HandlerMethodParameterAnnotations에 관하여 (@PathVariable, @RequestParam, @RequestBody, @ModelAttribute)

0. 개요

Spring의 컨트롤러 계층에서 HTTP 요청 데이터를 받아서 사용할 수 있게 하는

@ModelAttribute, @RequestBody, @PathVariable 등의 바인딩 어노테이션이 있다.

 

해당 기능들이 각각 어떤 값을 받을 때 유용한지 궁금해졌기 때문에 찾아본 내용들을 정리하여 작성해보려고 한다.

 

 

 

1. 소개

위의 어노테이션들은 HandlerMethodArgumentResolver라는 인터페이스에서 제공되는 기능이다.

 

해당 어노테이션을 사용하면 Spring에서 요청을 처리하는 순서는 아래와 같다.

1. 클라이언트가 요청을 보냄
2. DispatcherServlet에서 해당 요청 처리
3. HandlerMapping을 통해서 적절한 Handler를 탐색
   ex) 해당 어노테이션을 사용하는 컨트롤러 메서드를 찾아냄
4. HandlerAdapter를 통해 Handler 실행 준비
5. 요청된 값을 받아 메서드 파라미터에 바인딩한다.
6. 해당 컨트롤러 메서드 실행 및 리턴값 처리
7. DispatcherServlet이 최종 응답 반환

이 중 5번 순서에서 어노테이션이 동작한다고 볼 수 있다.

 

 

2. 어노테이션 별 작동 방식

2-1. @PathVariable

 

설명: URL 경로에서 값을 추출한다.

핸들러: PathVariableMethodArgumentResolver

예시:

@GetMapping("/users/{id}")
public String getUser(@PathVariable("id") Long id)

 

 

2-2. @RequestParam

 

설명: 쿼리 파라미터 or x-www-form-urlencoded 형식의 데이터에서 값을 추출한다.

핸들러: RequestParamMethodArgumentResolver

예시:

@GetMapping("/search")
public String search(@RequestParam String keyword) {
    // /search?keyword=spring => keyword = "spring"
}

 

 

2-3. @RequestBody

 

설명: HTTP 요청의 본문(body)을 Java 객체로 변환한다. (JSON → 객체)

핸들러: RequestResponseBodyMethodProcessor

조건: Content-Type: application/json 같은 설정이 필요하다.

예시:

@PostMapping("/user")
public String createUser(@RequestBody UserDto user)

 

 

 

2-4. @ModelAttribute

 

설명: 요청 파라미터를 객체에 바인딩. 폼 데이터를 자바 객체로 만들 때 사용한다.

핸들러: ModelAttributeMethodProcessor

예시:

@PostMapping("/register")
public String register(@ModelAttribute UserForm form) {
    // form에 name=Alice&age=30이 들어오면 자동 바인딩
}

 

 

 

각 어노테이션 별 특징을 비교 요약한 표이다.

어노테이션	데이터 위치	바인딩 대상	주로 쓰는 상황
@PathVariable	URL 경로 변수	단일 값	RESTful 경로 매핑
@RequestParam	쿼리 파라미터	단일 값	검색 필터, 간단한 값
@RequestBody	요청 본문	객체 전체	API(JSON 기반) 요청
@ModelAttribute	폼 파라미터	객체 전체	폼 기반 페이지 요청

 

 

 

3. 심화

• @RequestBody는 데이터 바인딩과 JSON 파싱을 위해 HttpMessageConverter를 사용한다.
  HttpMessageConverter는 HTTP 요청/응답 본문(body)을 Java 객체 ↔ JSON 등으로 변환하는 인터페이스이다.

 

• 어노테이션 없이 객체를 파라미터로 받으면 @ModelAttribute가 자동으로 선택된다.
  그렇기 때문에 JSON으로 본문을 받는데 어노테이션이 없이 파라미터로 받으면 동작하지 않게 된다.
  또한 String, int, long, boolean 등 기본 타입도 어노테이션 없이 받으면 오류가 발생한다.