📘 Spring Boot 입문 (5)@RequestBody · @RequestParam · @PathVariable 완전 정리 — API 요청 데이터 처리 핵심

REST API를 만들다 보면 항상 “요청 값은 어디서 받아야 하지?”라는 고민이 생깁니다.

스프링에서는 요청 데이터를 받는 방법이 명확하게 나뉘어 있고,
그 역할을 담당하는 애너테이션이 바로
@RequestBody, @RequestParam, @PathVariable 입니다.

이번 글에서는 언제 어떤 걸 써야 하는지,
실무에서 가장 많이 쓰는 패턴을 예제로 확실하게 정리합니다.

---

📌 목차

1. 요청 데이터는 어디에서 오는가?
2. @PathVariable — URL 경로 값
3. @RequestParam — 쿼리 파라미터
4. @RequestBody — JSON Body
5. 3가지 비교 정리
6. 실전 예제 (회원 API)
7. 자주 하는 실수
8. 대표 태그

---

1️⃣ 요청 데이터는 어디에서 오는가?

클라이언트가 서버에 요청을 보낼 때 데이터는 3가지 형태로 전달됩니다.

전달 위치	예시
URL Path	/users/1
Query String	/users?age=20
Request Body(JSON)	{ "email": "test@test.com" }

➡ 이 위치에 따라 사용하는 애너테이션이 다릅니다.

---

2️⃣ @PathVariable — URL 경로 값 받기

URL 경로 자체에 포함된 값을 받을 때 사용합니다.

✔ 예시 URL

 

/users/10

✔ Controller

 

@GetMapping("/users/{id}")
public String getUser(@PathVariable Long id) {
    return "user id = " + id;
}

✔ 특징

• 리소스를 식별할 때 사용
• REST API에서 가장 권장되는 방식
• ID, code 등에 주로 사용

 

3️⃣ @RequestParam — 쿼리 파라미터 받기

URL 뒤에 ?key=value 형태로 전달되는 값을 받을 때 사용합니다.

✔ 예시 URL

 

/users?age=20&name=tom

✔ Controller

 

@GetMapping("/users")
public String findUser(
        @RequestParam String name,
        @RequestParam int age
) {
    return name + ", " + age;
}

---

✔ 옵션 속성

@RequestParam(required = false) String name

@RequestParam(defaultValue = "0") int page

 

➡ 검색, 필터, 페이징에서 매우 자주 사용

---

4️⃣ @RequestBody — JSON Body 받기 (중요)

클라이언트가 JSON 형태로 데이터를 보낼 때 사용합니다.
POST / PUT / PATCH 요청에서 거의 필수입니다.

---

✔ DTO

 

public class UserRequestDto {
    private String email;
    private String password;
}

---

✔ Controller

 

@PostMapping("/users")
public String createUser(@RequestBody UserRequestDto dto) {
    return dto.getEmail();
}

➡ JSON → DTO 자동 매핑
➡ Jackson 라이브러리 사용

---

✔ 요청 예시 (JSON)

{
  "email": "test@test.com",
  "password": "1234"
}

 

5️⃣ 3가지 비교 정리 (한 눈에 보기)

구분위치사용 목적

구분	위치	사용 목적
@PathVariable	URL 경로	리소스 식별(ID)
@RequestParam	쿼리 스트링	검색/필터/옵션
@RequestBody	HTTP Body	데이터 생성/수정

---

6️⃣ 실전 예제 — 회원 API

✔ 회원 조회

 

@GetMapping("/users/{id}")
public UserResponseDto getUser(@PathVariable Long id) {
    return service.getUser(id);
}

---

✔ 회원 검색

 

@GetMapping("/users")
public List<UserResponseDto> search(
    @RequestParam(required = false) String email
) {
    return service.search(email);
}

---

✔ 회원 등록

@PostMapping("/users")
public void create(@RequestBody UserRequestDto dto) {
    service.create(dto);
}

 

➡ 이 패턴이 실무의 기본형입니다.

---

7️⃣ 자주 하는 실수

❌ GET 요청에 @RequestBody 사용

→ 권장하지 않음

❌ DTO 없이 Map으로 받기

→ 유지보수 지옥

❌ PathVariable과 Param 혼용

→ 역할 명확히 구분해야 함

❌ JSON 필드명과 DTO 필드명 불일치

→ 매핑 실패 발생

 

 

📘 다음 글 예고

👉 Spring Boot 입문 (6) — ResponseEntity, HTTP Status, API 응답 설계 기본