ResponseEntity

Spring 기반 개발을 하다 보면 서비스 로직 작성 중에 ResponseEntity를 정말 자주 보게 된다.

💻 ResponseEntity

HTTP 응답 전체를 직접 구성할 수 있는 Spring의 클래스

ResponseEntity가 제어할 수 있는 3요소

• HTTP Status Code
• HTTP Headers
• Response Body (JSON, String, Object)

왜 ResponseEntity를 사용하는가

1️⃣ HTTP status코드를 정확히 내려줄 수 있음

리소스 생성 시 201 상태로 명확하게 응답예시

return ResponseEntity.status(HttpStatus.CREATED).body(data);

2️⃣ 응답 Header 세팅이 필요할 때

JWT, Cookie기반 인증시 필수적

return ResponseEntity.ok()
        .header("Set-Cookie", cookie)
        .body(userInfo);

3️⃣ body에 객체를 자유롭게 담을 수 있음

담긴 객체는 자동으로 JSON문자열로 변환 됨

return ResponseEntity.ok(new UserResponse(...));

4️⃣ 에러 핸들링을 명확하게 할 수 있음

에러 상황에서 적절한 상태 코드와 함께 커스텀 에러 메시지 전달이 가능

// 404 에러 응답 예시
return ResponseEntity.status(HttpStatus.NOT_FOUND)
        .body(new ErrorResponse("USER_NOT_FOUND", "해당 사용자를 찾을 수 없습니다."));

// 400 에러 응답 예시
return ResponseEntity.badRequest()
        .body(new ErrorResponse("INVALID_INPUT", "이메일 형식이 올바르지 않습니다."));

정리

다음과 같은 상황에서는 ResponseEntity는 선택이 아닌 필수이다.

• 인증/인가 구현 시: JWT 토큰이나 세션 쿠키를 헤더에 담아 전달
• RESTful API 설계 시: 리소스 생성(201), 수정(200), 삭제(204) 등 정확한 상태 코드 반환
• 에러 핸들링 시: 4xx, 5xx 에러와 함께 커스텀 에러 메시지 전달

단순히 데이터만 반환하는 @ResponseBody와 달리, ResponseEntity는 HTTP 통신의 모든 측면을 제어할 수 있게 해주기 때문이다.