🌐 @RequestBody, @ResponseBody vs HttpEntity(RequestEntity, ResponseEntity)
- 스프링에서 HTTP Body를 처리하는 5가지 방식 정리
REST API를 개발하다 보면 HTTP 요청과 응답의 본문(body)을 직접 다뤄야 할 일이 많습니다.
이때 사용할 수 있는 방법이 여러 가지 있는데, 대표적으로 다음과 같은 것들이 있습니다.
@RequestBody, @ResponseBody, HttpEntity, RequestEntity, ResponseEntity
이름이 비슷해서 헷갈리기 쉽지만, 의도와 활용 방식에 차이가 있습니다.
이번 글에서는 이 5가지의 차이를 명확하게 비교해보겠습니다.
1️⃣ @RequestBody란?
HTTP 요청의 body 내용을 자바 객체로 변환해주는 어노테이션입니다.
→ JSON, XML, plain text 등을 객체로 바꿔줍니다.
@PostMapping("/hello")
public String hello(@RequestBody UserDto user) {
return "Hello " + user.getName();
}
특징
- 요청 본문(JSON 등)을 객체로 바로 변환
- 내부적으로 HttpMessageConverter가 동작
- 필수 값 (기본적으로 body가 없으면 400 Bad Request 발생)
2️⃣ @ResponseBody란?
자바 객체를 HTTP 응답의 body로 직접 변환해주는 어노테이션입니다.
→ JSON, XML 등으로 자동 직렬화됩니다.
@GetMapping("/user")
@ResponseBody
public UserDto getUser() {
return new UserDto("철준", 35);
}
특징
- 반환값이 뷰 이름이 아닌 데이터 자체로 응답
- @RestController를 쓰면 클래스 전체에 @ResponseBody 적용됨
3️⃣ HttpEntity<T>란?
요청 또는 응답에서 HTTP 본문(body) + 헤더 정보를 함께 가져오거나 응답할 수 있는 객체입니다.
@PostMapping("/entity")
public String handle(HttpEntity<UserDto> request) {
HttpHeaders headers = request.getHeaders();
UserDto body = request.getBody();
...
}
특징
- 본문과 헤더를 동시에 받을 수 있음
- 파라미터로만 사용 가능 (리턴 시에는 ResponseEntity를 씀)
4️⃣ RequestEntity<T>란?
HttpEntity를 상속한 클래스이며, 요청 메서드, URL, 헤더, 본문 등 더 많은 정보를 포함합니다.
@PostMapping("/request-entity")
public String handleRequest(RequestEntity<UserDto> request) {
HttpMethod method = request.getMethod();
URI url = request.getUrl();
UserDto body = request.getBody();
...
}
- HttpEntity + HTTP method, URL 정보 포함
- 요청 정보를 보다 정밀하게 다루고 싶을 때 사용
5️⃣ ResponseEntity<T>란?
응답의 본문 + 상태 코드 + 헤더를 직접 제어할 수 있는 객체입니다.
→ 가장 많이 사용되는 응답 타입
@GetMapping("/response")
public ResponseEntity<UserDto> response() {
UserDto user = new UserDto("철준", 35);
return ResponseEntity
.status(HttpStatus.CREATED)
.header("Custom-Header", "hello")
.body(user);
}
특징
- HTTP 상태 코드, 헤더, 바디를 자유롭게 설정 가능
- REST API 응답 커스터마이징에 최적
📊 전체 비교표
항목본문 처리헤더 접근상태 코드 설정사용 위치비고
| 항목 |
본문 처리 |
헤더 접근 |
상태 코드 설정 |
사용 위치 |
비고 |
| @RequestBody |
✅ |
❌ |
❌ |
파라미터 |
요청 본문을 객체로 변환 |
| @ResponseBody |
✅ |
❌ |
❌ |
반환값 |
객체를 JSON 등으로 응답 |
| HttpEntity<T> |
✅ |
✅ |
❌ |
파라미터 |
헤더 + 바디 접근 가능 |
| RequestEntity<T> |
✅ |
✅ |
❌ |
파라미터 |
HttpMethod, URL 정보 포함 |
| ResponseEntity<T> |
✅ |
✅ |
✅ |
반환값 |
응답 제어용으로 자주 사용 |
💡 정리 포인트
- @RequestBody는 클라이언트 → 서버 요청 본문(JSON 등)을 객체로 바꾸는 도구
- @ResponseBody는 서버 → 클라이언트 응답을 객체 → JSON 등으로 바꾸는 도구
- HttpEntity는 본문 + 헤더 모두 보고 싶을 때 사용
- RequestEntity는 요청의 HTTP 메서드, URI까지 알고 싶을 때
- ResponseEntity는 응답의 상태 코드, 헤더, 본문 모두 직접 조작할 수 있을 때 사용
✨ 마무리
Spring MVC에서 HTTP 요청과 응답을 다룰 때는 상황에 맞는 도구를 선택하는 것이 중요합니다.
- 단순 요청이라면 @RequestBody, @ResponseBody로 간단하게 처리
- 헤더나 상태 코드까지 조작이 필요하다면 HttpEntity, ResponseEntity를 활용하자.
🧰 HttpEntity, RequestEntity, ResponseEntity는 Body만 다룰까?
- HTTP 요청/응답의 전체 구조를 함께 다루는 '컨테이너' 입니다.
Spring MVC에서 HttpEntity, RequestEntity, ResponseEntity는 종종 "HTTP Body를 처리할 때 사용하는 객체"로 소개됩니다.
하지만 이 클래스들은 본문(body)뿐 아니라 헤더(header)까지 포함해서, 더 넓은 역할을 수행합니다.
이 클래스들은 "HTTP 요청/응답을 구성하는 모든 정보(본문, 헤더, 상태 코드 등)를 함께 담는 컨테이너"입니다.
📦 HTTP 요청/응답은 어떤 정보로 구성돼 있을까?
HTTP 메시지는 크게 다음 3가지로 구성됩니다:
- 상태 라인 / 요청 라인 (Request: GET /hello, Response: HTTP/1.1 200 OK)
- 헤더(Header) — Content-Type, Authorization 등
- 본문(Body) — JSON, XML, 텍스트 등 실질적인 데이터
☝️ 여기서 핵심 질문:
"스프링에서는 이 모든 걸 어떻게 한 번에 다룰 수 있을까?"
그때 등장하는 것이 바로:
- HttpEntity<T>
- RequestEntity<T>
- ResponseEntity<T>
이들은 단순히 Body만 처리하는 것이 아니라,
→ HTTP 메시지를 이루는 구조 전체를 객체로 감싸서 통합적으로 다루는 도구입니다.
1️⃣ HttpEntity<T> - 요청/응답의 헤더 + 바디를 함께 담는 기본 컨테이너
public class HttpEntity<T> {
private final HttpHeaders headers;
private final T body;
}
- headers: 요청 또는 응답의 HTTP 헤더
- body: JSON 등 본문 데이터
✔ 특징
- 요청과 응답 양쪽에서 사용 가능
- 상태 라인(메서드, 상태코드)은 포함하지 않음
2️⃣ RequestEntity<T> - 요청 전체 정보를 모두 담고 싶은 경우
public class RequestEntity<T> extends HttpEntity<T> {
private final HttpMethod method;
private final URI url;
}
- HttpEntity의 기능 + 요청 라인(HTTP 메서드, URL) 정보까지 포함
- 예: POST /api/users, GET /api/data
✔ 특징
- HTTP 요청 메시지의 구조 전체를 객체로 표현 가능
- 요청 처리 전에 메서드나 URI 조건을 확인하고 분기할 수 있음
3️⃣ ResponseEntity<T> - 응답 전체 구조를 구성하고 반환하는 객체
public class ResponseEntity<T> extends HttpEntity<T> {
private final HttpStatus status;
}
- HttpEntity의 기능 + 응답 상태 코드(200 OK, 404 Not Found 등)까지 포함
✔ 특징
- 바디, 헤더, 상태 코드 모두 커스터마이징 가능
- 실제 운영 API에서 가장 자주 쓰이는 반환 타입
📊 전체 비교 정리
| 항목 |
바디 |
헤더 |
상태 코드 |
라인 정보(method, URL 등) |
사용 목적 |
| HttpEntity<T> |
✅ |
✅ |
❌ |
❌ |
요청/응답 헤더+바디 처리 |
| RequestEntity<T> |
✅ |
✅ |
❌ |
✅ |
요청의 메서드, URL까지 필요할 때 |
| ResponseEntity<T> |
✅ |
✅ |
✅ |
❌ |
응답의 상태 코드까지 제어하고 싶을 때 |
💡 실전에서 언제 쓰일까?
요청 처리할 때
@PostMapping("/auth")
public String auth(HttpEntity<?> request) {
HttpHeaders headers = request.getHeaders();
...
}
→ 요청의 헤더와 바디를 함께 확인해야 할 때 유용
응답 보낼 때
@GetMapping("/download")
public ResponseEntity<Void> download() {
HttpHeaders headers = new HttpHeaders();
headers.add("Content-Disposition", "attachment; filename=data.csv");
return new ResponseEntity<>(headers, HttpStatus.OK);
}
→ 본문 없이도 헤더와 상태코드를 명확하게 제어 가능
✨ 마무리 요약
- HttpEntity, RequestEntity, ResponseEntity는 단순한 Body 전달용이 아님
- → HTTP 메시지의 모든 구조(본문, 헤더, 상태 코드, 요청 메서드 등)를 객체 형태로 다루는 도구
- 상황에 따라 필요한 정보를 얼마나 정밀하게 제어할 것인지에 따라 적절한 클래스를 선택하면 됩니다.
