SpringBoot 요청 매핑 어노테이션 차이 완벽 정리

SpringBoot에서 클라이언트의 요청을 처리할 때,
서버는 HTTP 요청 데이터 중 쿼리 파라미터, 경로 변수, 요청 본문 등을 분석하여 메서드에 매핑합니다.
이때 사용하는 주요 어노테이션이 바로 @RequestParam, @PathVariable, @RequestBody입니다.
이번 글에서는 이 세 가지 어노테이션의 차이를 구체적인 예시와 함께 정리해 보겠습니다.

1. HTTP 요청 데이터는 어디에서 오는가?

HTTP 요청은 크게 다음과 같은 방식으로 데이터를 전달합니다.

Query Parameter: GET /search?keyword=java
Path Variable: GET /users/1234
Request Body: POST /users와 함께 JSON 전송

Spring에서는 각각의 방식에 따라 적절한 어노테이션을 사용하여 데이터를 컨트롤러 메서드에 전달받습니다.

2. @RequestParam의 동작 방식

@RequestParam은 쿼리 파라미터나 폼 데이터를 받는 데 사용됩니다.

@GetMapping("/search")
public String search(@RequestParam String keyword) {
    return "검색어: " + keyword;
}

?keyword=java 형식으로 전달된 파라미터를 자동 매핑
기본적으로 필수이며, required = false 옵션으로 선택값 처리 가능
주로 GET 요청 또는 form 전송에 사용

✅ 다수의 키-값 쌍을 전달할 때 편리하며, 단순한 문자열이나 숫자 매핑에 적합합니다.

3. @PathVariable의 특징과 사용 예

@PathVariable은 URI 경로에 포함된 값을 변수로 추출하는 데 사용됩니다.

@GetMapping("/users/{id}")
public String getUser(@PathVariable Long id) {
    return "사용자 ID: " + id;
}

URL 경로 자체가 데이터를 포함
가독성이 뛰어나 RESTful한 API 구성에 적합
메서드 매개변수 이름과 {} 내부 이름이 같아야 자동 매핑됨

📌 주로 ID 기반 리소스 조회, 삭제, 상세 페이지 등에서 활용됩니다.

4. @RequestBody의 역할과 주의점

@RequestBody는 **HTTP 요청 본문(body)**에 포함된 데이터를 객체로 변환하여 매핑합니다.

@PostMapping("/users")
public String createUser(@RequestBody UserDto dto) {
    return "생성된 사용자: " + dto.getName();
}

JSON, XML 등의 본문 데이터를 자바 객체로 변환 (Jackson 사용)
대량의 구조화된 데이터 전송 시 유용
POST, PUT 등에서 복합 데이터 구조 처리에 최적화

⚠️ 반드시 Content-Type: application/json 헤더와 함께 사용되어야 하며, DTO 객체에 기본 생성자와 getter/setter가 필요합니다.

5. 실무 기준 어노테이션 선택 가이드

어노테이션	데이터 출처	주 사용 용	특징
@RequestParam	쿼리 파라미터	검색, 필터, 간단한 폼	문자열 위주
@PathVariable	URL 경로 변수	리소스 조회/삭제	RESTful URL 설계에 적합
@RequestBody	요청 본문(JSON)	객체 생성/수정	구조화된 데이터 처리

☑️ 실무에서는 요청 방식에 따라 적절한 어노테이션을 조합하여 사용하는 것이 일반적입니다.

✅ 마무리

SpringBoot에서 @RequestParam, @PathVariable, @RequestBody는 각기 다른 HTTP 요청 형식을 처리하기 위해 사용됩니다.
이 세 가지의 차이를 정확히 이해하고 목적에 맞게 선택하면, 더 명확하고 유지보수하기 쉬운 API를 설계할 수 있습니다.

기록기록