Spring Boot RequestBody와 RequestParam 차이 쉽게 이해하기

Spring Boot에서 RequestBody와 RequestParam의 차이를 쉽게 이해할 수 있도록 정리해 드립니다. GET과 POST 요청의 차이부터 JSON 처리 방식, 실무에서 언제 어떤 어노테이션을 사용해야 하는지 예제와 비교표를 통해 자세히 알아보실 수 있습니다.

Spring Boot RequestBody와 RequestParam 차이

Spring Boot로 REST API를 개발하다 보면 가장 자주 사용하는 어노테이션이 @RequestParam과 @RequestBody입니다. 처음에는 두 어노테이션 모두 클라이언트의 데이터를 전달받는 역할처럼 보이기 때문에 언제 무엇을 사용해야 하는지 헷갈리는 경우가 많습니다.

특히 spring requestparam requestbody, spring requestparam vs requestbody, spring boot requestbody requestparam과 같은 검색을 하는 개발자라면 GET 요청과 POST 요청, URL 파라미터와 JSON Body의 차이를 정확하게 이해하고 싶은 경우가 많습니다.

이번 글에서는 두 어노테이션의 역할과 차이점을 실무 관점에서 쉽게 설명해 드리겠습니다.

---

01. RequestParam과 RequestBody의 핵심 차이

이번 섹션에서는 두 어노테이션이 데이터를 어디에서 가져오는지부터 이해해 보겠습니다.

✓ 가장 큰 차이

가장 중요한 차이는 데이터를 전달받는 위치입니다.

구분RequestParamRequestBody

데이터 위치	URL Query String 또는 Form Data	HTTP Body
주요 요청 방식	GET, DELETE	POST, PUT, PATCH
대표 데이터	id=10&name=test	JSON
매핑 대상	기본 타입, 문자열	객체(DTO)

예를 들어 다음과 같은 URL이 있다고 가정해 보겠습니다.

/users?id=10&name=kim

 

이 경우에는 URL에 포함된 값을 가져오기 때문에 @RequestParam을 사용합니다.

반면 아래와 같이 JSON을 전송한다면 @RequestBody를 사용합니다.

 

{
  "name": "Kim",
  "age": 30
}

 

즉, URL에서 가져오면 RequestParam, Body에서 가져오면 RequestBody라고 이해하시면 가장 쉽습니다.

---

02. RequestParam 사용 방법

이번 섹션에서는 가장 많이 사용하는 RequestParam 예제를 살펴보겠습니다.

✓ 기본 사용 예제

 

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

 

호출 예시는 다음과 같습니다.

GET /user?name=Kim&age=30

 

Spring은 URL의 값을 자동으로 변수에 매핑해 줍니다.

✓ 선택값 처리

필수값이 아니라면 required 옵션을 사용할 수 있습니다.

 

@GetMapping("/user")
public String getUser(
    @RequestParam(required = false) String name
){
    return name;
}

 

✓ 기본값 설정

값이 없을 경우 기본값을 지정할 수도 있습니다.

 

@RequestParam(defaultValue = "guest")
String name

 

실무에서는 검색 기능이나 페이징 처리에서 매우 많이 사용됩니다.

예를 들어 다음과 같은 API가 대표적입니다.

/products?page=1
/products?keyword=laptop
/products?size=20

 

---

03. RequestBody 사용 방법

이번 섹션에서는 JSON 데이터를 객체로 변환하는 방법을 알아보겠습니다.

✓ DTO 생성

 

public class UserRequest {

    private String name;

    private int age;

    // Getter Setter
}

 

✓ Controller 작성

 

@PostMapping("/user")
public String saveUser(
    @RequestBody UserRequest request
){
    return request.getName();
}

 

요청 데이터입니다.

 

{
    "name":"Kim",
    "age":30
}

 

Spring Boot는 HTTP Body에 있는 JSON을 읽어 DTO 객체로 자동 변환합니다.

이 과정은 기본적으로 HttpMessageConverter가 처리하며, 일반적인 Spring Boot 환경에서는 JSON 라이브러리를 이용하여 객체로 매핑됩니다.

---

04. 언제 RequestParam을 사용해야 할까요?

이번 섹션에서는 실무에서 RequestParam을 사용하는 대표적인 사례를 정리해 보겠습니다.

✓ 조회 API

가장 많이 사용하는 경우입니다.

GET /users?id=1

 

✓ 검색 기능

GET /board?keyword=spring

 

✓ 페이지 이동

GET /products?page=2

 

✓ 정렬 조건

GET /products?sort=price

 

조회 조건처럼 URL에 노출되어도 문제가 없는 데이터라면 대부분 RequestParam을 사용하는 것이 일반적입니다.

---

05. 언제 RequestBody를 사용해야 할까요?

이번 섹션에서는 RequestBody가 적합한 상황을 살펴보겠습니다.

✓ 회원가입

 

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

 

✓ 게시글 작성

본문이 길어질수록 JSON으로 전달하는 것이 적합합니다.

✓ 회원 정보 수정

PUT 또는 PATCH 요청에서는 여러 개의 필드를 한 번에 수정하는 경우가 많습니다.

✓ 주문 생성

주문 상품이 여러 개인 경우에는 객체 구조가 복잡해질 수 있습니다.

 

{
    "userId":1,
    "items":[
        {
            "productId":10,
            "count":2
        }
    ]
}

 

이처럼 계층 구조를 가진 데이터는 RequestBody가 훨씬 적합합니다.

---

06. RequestParam과 RequestBody를 함께 사용할 수 있을까요?

이번 섹션에서는 두 어노테이션을 동시에 사용하는 방법을 알아보겠습니다.

✓ 함께 사용하는 예제

 

@PostMapping("/users")
public String saveUser(

    @RequestParam String token,

    @RequestBody UserRequest request

){
    return "success";
}

 

호출 예시는 다음과 같습니다.

POST /users?token=abcd

 

Body입니다.

 

{
    "name":"Kim",
    "age":30
}

 

이처럼 인증 토큰이나 간단한 옵션은 URL로 전달하고, 실제 데이터는 Body로 전달하는 방식도 많이 사용됩니다.

---

07. RequestParam vs RequestBody 비교 정리

이번 섹션에서는 핵심 내용을 한 번에 비교해 보겠습니다.

✓ 비교표

항목RequestParamRequestBody

데이터 위치	URL	Body
대표 방식	GET	POST, PUT, PATCH
데이터 형태	문자열 중심	JSON
객체 전달	불편함	매우 편리함
대용량 데이터	비추천	적합
DTO 사용	거의 사용하지 않음	주로 사용함
검색 API	적합	비추천
등록 API	비추천	적합

이 표만 기억하셔도 대부분의 상황에서 어떤 어노테이션을 사용해야 하는지 쉽게 판단하실 수 있습니다.

---

08. 실무에서 가장 많이 사용하는 패턴

이번 섹션에서는 REST API에서 자주 사용하는 패턴을 소개해 드리겠습니다.

✓ 조회

GET /users?page=1

 

→ RequestParam

✓ 회원 등록

POST /users

 

→ RequestBody

✓ 회원 수정

PUT /users/1

 

→ RequestBody

✓ 삭제

DELETE /users?id=1

 

또는

DELETE /users/1

 

삭제 요청은 API 설계 방식에 따라 RequestParam 또는 PathVariable을 사용할 수 있습니다.

---

09. 자주 발생하는 실수

이번 섹션에서는 초보 개발자가 자주 겪는 문제를 정리해 보겠습니다.

✓ GET 요청에서 JSON을 보내려고 하는 경우

일반적인 GET 요청에서는 URL 파라미터를 사용하는 것이 일반적입니다.

✓ RequestBody 없이 JSON을 보내는 경우

JSON을 전송하면서 Controller에서 RequestBody를 사용하지 않으면 원하는 값이 매핑되지 않을 수 있습니다.

✓ RequestParam으로 객체를 모두 전달하려는 경우

전달해야 하는 데이터가 많아질수록 URL이 길어지고 관리가 어려워질 수 있습니다. 여러 필드를 포함하는 데이터는 RequestBody와 DTO를 사용하는 편이 유지보수에 유리합니다.

✓ DTO 없이 Map만 사용하는 경우

간단한 테스트에서는 가능하지만, 실제 프로젝트에서는 DTO를 사용하는 편이 가독성과 유지보수 측면에서 도움이 되는 경우가 많습니다.

---

10. 마무리

이번 글에서는 Spring Boot RequestBody와 RequestParam 차이 쉽게 이해하기를 중심으로 두 어노테이션의 역할과 사용 시점을 살펴보았습니다.

정리하면 RequestParam은 URL의 데이터를 가져오는 용도, RequestBody는 HTTP Body의 JSON 데이터를 객체로 변환하는 용도라고 이해하시면 됩니다.

REST API를 설계할 때 조회 기능은 RequestParam을, 등록이나 수정처럼 객체 데이터를 전달하는 경우에는 RequestBody를 사용하는 패턴이 가장 널리 활용됩니다. 두 어노테이션의 역할을 정확히 이해하면 API의 가독성과 유지보수성이 높아지고, 클라이언트와 서버 간의 데이터 전달 방식도 훨씬 명확하게 설계하실 수 있습니다.

---

FAQ

Q1. RequestParam과 RequestBody를 동시에 사용할 수 있나요?

가능합니다. URL의 간단한 값은 RequestParam으로 받고, JSON 데이터는 RequestBody로 함께 전달받을 수 있습니다.

Q2. GET 요청에서도 RequestBody를 사용할 수 있나요?

기술적으로 일부 환경에서는 가능할 수 있지만, 일반적인 REST API 설계에서는 GET 요청은 URL 파라미터를 사용하고 Body를 사용하지 않는 것이 일반적입니다.

Q3. JSON 데이터를 받을 때는 반드시 RequestBody를 사용해야 하나요?

일반적으로 HTTP Body에 전달된 JSON 데이터를 DTO 객체로 매핑하려면 RequestBody를 사용합니다.

Q4. RequestParam은 DTO를 사용할 수 없나요?

여러 파라미터를 객체로 바인딩하는 방법도 있지만, 일반적으로는 단순한 조회 조건이나 검색 조건을 전달할 때 RequestParam을 많이 사용합니다.

Q5. 실무에서는 어떤 방식을 더 많이 사용하나요?

조회 기능에서는 RequestParam을 많이 사용하며, 등록·수정 API에서는 RequestBody와 DTO를 사용하는 방식이 일반적으로 활용됩니다.

관련글

• 폐쇄망 Spring Boot vscode 개발 환경에서 핫리로드 적용하는 방법
• Spring Boot 요청 DTO 검증을 위한 Validation 사용 방법 완벽 가이드
• Spring Boot Lombok 실무 사용법: 설치부터 Annotation 적용과 오류 해결까지