Spring Boot에서 REST API 응답 형식 ResponseEntity 사용법을 쉽게 정리해 드립니다. ResponseEntity 응답 코드 설정 방법, HTTP Status 활용법, 헤더 추가, JSON 응답 예제, 실무에서 많이 사용하는 패턴과 예외 처리 방법까지 한 번에 이해하실 수 있습니다.
REST API를 개발하다 보면 성공과 실패를 어떻게 응답해야 하는지, HTTP 상태 코드는 어떻게 내려야 하는지, JSON 데이터를 어떤 형태로 반환해야 하는지 고민하게 됩니다.
이때 Spring Boot에서 가장 많이 사용하는 클래스가 바로 ResponseEntity입니다.
ResponseEntity를 사용하면 단순히 데이터를 반환하는 것에서 끝나지 않고 응답 데이터, HTTP 상태 코드(Status Code), 응답 헤더(Header)까지 한 번에 제어할 수 있습니다.
이번 글에서는 ResponseEntity의 기본 개념부터 실무에서 자주 사용하는 예제까지 순서대로 살펴보겠습니다.
01. 핵심 기준 한눈에 보기
이번 섹션에서는 ResponseEntity가 무엇이며 언제 사용하는 것이 좋은지 살펴보겠습니다.
✓ ResponseEntity란 무엇인가요?
ResponseEntity는 Spring Framework에서 제공하는 HTTP 응답 객체입니다.
일반적으로 Controller에서 객체만 반환하면 Spring이 자동으로 JSON으로 변환하여 응답합니다.
예를 들어 다음과 같은 코드가 있습니다.
@GetMapping("/user")
public User getUser() {
return userService.find();
}이 방법도 사용할 수 있지만 HTTP 상태 코드나 헤더를 세밀하게 제어하기는 어렵습니다.
ResponseEntity를 사용하면 다음 세 가지를 모두 직접 설정할 수 있습니다.
- 응답 데이터(Body)
- HTTP 상태 코드(Status)
- 응답 헤더(Header)
그래서 대부분의 REST API에서는 ResponseEntity 사용을 권장하는 경우가 많습니다.
02. ResponseEntity 기본 사용법
이번 섹션에서는 가장 많이 사용하는 생성 방법을 알아보겠습니다.
✓ 가장 기본적인 응답
@GetMapping("/user")
public ResponseEntity<User> getUser() {
User user = userService.find();
return ResponseEntity.ok(user);
}응답 결과는 다음과 같습니다.
HTTP Status
200 OKBody
{
"id":1,
"name":"Kim"
}가장 많이 사용하는 형태이며 200 OK를 자동으로 반환합니다.
✓ 상태 코드 직접 지정하기
return ResponseEntity.status(HttpStatus.CREATED)
.body(user);응답 결과
201 Created주로 회원가입이나 게시글 등록처럼 새로운 리소스를 생성했을 때 사용합니다.
✓ 응답 데이터 없이 반환하기
return ResponseEntity.noContent().build();응답 결과
204 No Content삭제 API에서 자주 사용합니다.
03. ResponseEntity 응답 코드 정리
이번 섹션에서는 실무에서 자주 사용하는 HTTP 상태 코드를 정리해 보겠습니다.
✓ 많이 사용하는 상태 코드
상태 코드의미사용 예시
| 200 OK | 조회 성공 | GET |
| 201 Created | 생성 성공 | POST |
| 204 No Content | 삭제 성공 | DELETE |
| 400 Bad Request | 잘못된 요청 | Validation 실패 |
| 401 Unauthorized | 인증 실패 | 로그인 필요 |
| 403 Forbidden | 권한 없음 | 접근 거부 |
| 404 Not Found | 데이터 없음 | 조회 실패 |
| 500 Internal Server Error | 서버 오류 | 예외 발생 |
상황에 맞는 상태 코드를 사용하는 것이 REST API 설계에서 매우 중요합니다.
04. JSON 응답 형식을 통일하는 방법
이번 섹션에서는 실무에서 많이 사용하는 공통 응답 구조를 살펴보겠습니다.
✓ 공통 응답 DTO 만들기
실무에서는 대부분 응답 형식을 통일합니다.
public class ApiResponse<T> {
private boolean success;
private String message;
private T data;
}응답 예시는 다음과 같습니다.
{
"success":true,
"message":"조회 성공",
"data":{
"id":1,
"name":"Kim"
}
}Controller에서는 다음처럼 사용할 수 있습니다.
return ResponseEntity.ok(
new ApiResponse<>(
true,
"조회 성공",
user
)
);이렇게 하면 모든 API 응답 구조가 일정하게 유지됩니다.
05. 오류 응답 만들기
이번 섹션에서는 실패 응답을 만드는 방법을 알아보겠습니다.
✓ 잘못된 요청
return ResponseEntity.badRequest()
.body(
new ApiResponse<>(
false,
"잘못된 요청입니다.",
null
)
);응답 결과
{
"success":false,
"message":"잘못된 요청입니다.",
"data":null
}✓ 데이터가 없는 경우
return ResponseEntity.status(HttpStatus.NOT_FOUND)
.body(
new ApiResponse<>(
false,
"사용자를 찾을 수 없습니다.",
null
)
);HTTP Status
404 Not Found06. ResponseEntity에서 Header 추가하기
이번 섹션에서는 응답 헤더를 추가하는 방법을 알아보겠습니다.
✓ Header 설정
return ResponseEntity.ok()
.header("API-Version","1.0")
.body(user);응답 Header
API-Version: 1.0파일 다운로드, 캐시 설정, 인증 토큰 전달 등 다양한 상황에서 활용할 수 있습니다.
07. 실무에서 가장 많이 사용하는 패턴
이번 섹션에서는 프로젝트에서 자주 사용하는 구조를 소개해 드리겠습니다.
✓ 조회
return ResponseEntity.ok(data);✓ 등록
return ResponseEntity.status(HttpStatus.CREATED)
.body(data);✓ 수정
return ResponseEntity.ok(data);✓ 삭제
return ResponseEntity.noContent().build();✓ 예외 발생
return ResponseEntity.status(HttpStatus.BAD_REQUEST)
.body(errorResponse);이 패턴만 익혀도 대부분의 REST API를 구현하는 데 큰 어려움이 없습니다.
08. ExceptionHandler와 함께 사용하기
이번 섹션에서는 예외 처리와 ResponseEntity를 함께 사용하는 방법을 알아보겠습니다.
✓ 전역 예외 처리
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(Exception.class)
public ResponseEntity<ApiResponse<Void>> handle(Exception e){
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
.body(
new ApiResponse<>(
false,
e.getMessage(),
null
)
);
}
}이렇게 구현하면 모든 예외 응답 형식을 동일하게 유지할 수 있습니다.
실무에서는 Controller마다 try-catch를 작성하기보다는 전역 예외 처리를 사용하는 경우가 많습니다.
09. ResponseEntity를 사용해야 하는 이유
이번 섹션에서는 ResponseEntity를 사용하는 장점을 정리해 보겠습니다.
✓ 장점
- HTTP 상태 코드를 자유롭게 지정할 수 있습니다.
- 응답 헤더를 함께 설정할 수 있습니다.
- JSON 응답 형식을 통일하기 쉽습니다.
- REST API 표준을 적용하기 편리합니다.
- 예외 처리와 함께 사용하기 좋습니다.
- 프론트엔드와 협업하기 쉬운 구조를 만들 수 있습니다.
반대로 단순한 문자열이나 화면(View)만 반환하는 경우에는 ResponseEntity가 반드시 필요한 것은 아닙니다.
REST API에서는 대부분 ResponseEntity를 사용하는 것이 유지보수 측면에서도 유리합니다.
10. 마무리
이번 글에서는 REST API ResponseEntity 사용법을 중심으로 기본 개념부터 응답 코드, JSON 응답 구조, Header 설정, 예외 처리까지 살펴보았습니다.
ResponseEntity는 단순히 데이터를 반환하는 기능을 넘어 HTTP 상태 코드와 응답 형식을 명확하게 표현할 수 있도록 도와주는 핵심 도구입니다.
특히 실무에서는 응답 형식을 하나로 통일하고, 성공과 실패를 일관성 있게 처리하는 것이 매우 중요합니다. 이러한 구조를 적용하면 프론트엔드와의 협업이 쉬워지고 유지보수성도 높아질 수 있습니다.
FAQ
Q1. ResponseEntity를 반드시 사용해야 하나요?
반드시 사용해야 하는 것은 아닙니다. 단순한 데이터를 반환하는 경우에는 객체만 반환해도 됩니다. 다만 HTTP 상태 코드나 헤더를 함께 제어해야 하는 REST API에서는 ResponseEntity를 사용하는 경우가 많습니다.
Q2. ResponseEntity와 @ResponseBody는 어떤 차이가 있나요?
@ResponseBody는 반환 객체를 HTTP 응답 본문으로 변환하는 역할을 합니다. ResponseEntity는 응답 본문뿐 아니라 상태 코드와 헤더까지 함께 제어할 수 있다는 차이가 있습니다.
Q3. ResponseEntity.ok()와 status(HttpStatus.OK)는 같은 의미인가요?
네, 결과적으로는 모두 HTTP 200 OK를 반환합니다. 다만 ResponseEntity.ok()가 더 간결하여 일반적인 성공 응답에서 많이 사용됩니다.
Q4. ResponseEntity에서 제네릭을 사용하는 이유는 무엇인가요?
ResponseEntity<T> 형태로 사용하면 반환하는 데이터의 타입을 명확하게 표현할 수 있어 컴파일 시점의 타입 안정성과 코드 가독성을 높일 수 있습니다.
Q5. 실무에서는 응답 객체를 따로 만드는 것이 좋을까요?
프로젝트 규모가 커질수록 성공 여부, 메시지, 데이터 등을 포함하는 공통 응답 객체를 만들어 사용하는 경우가 많습니다. 이렇게 하면 API 응답 형식을 일관성 있게 유지하기 쉽습니다.
'실무개발' 카테고리의 다른 글
| REST API HTTP 상태 코드 제대로 사용하는 방법 (0) | 2026.07.17 |
|---|---|
| JSON 응답 구조 표준화하는 방법과 API 설계 팁 (1) | 2026.07.17 |
| Spring Boot DTO 설계 시 꼭 알아야 하는 작성 원칙 (0) | 2026.07.15 |
| Jackson ObjectMapper 사용법과 JSON 변환 예제 정리 (0) | 2026.07.14 |
| Spring Boot JSON 데이터 처리 과정 완벽 이해하기 (0) | 2026.07.13 |