Spring Web Responseentity

ResponseEntity<ApiResponse>를 사용하는 것과 ApiResponse만 반환하는 것의 차이는 다음과 같습니다:

1. ResponseEntity<ApiResponse>를 사용하는 경우 java 복사 편집 @GetMapping public ResponseEntity<ApiResponse> getClients(ClientSearchRequestDto requestDto) { List clients = clientSearchService.getClients(requestDto.toClientSearchParams()); return ResponseEntity.ok(ApiResponse.success(new ClientSearchResponseDto(clients))); } ✅ 장점:

HTTP 응답 코드와 헤더를 명시적으로 설정할 수 있다. ResponseEntity.ok()를 사용하면 응답 코드가 200(OK)로 설정되지만, 필요하면 ResponseEntity.status(HttpStatus.BAD_REQUEST).body(…)처럼 다른 상태 코드도 설정할 수 있다. API 설계에서 보다 세밀한 HTTP 응답 제어가 가능하다.

1. ApiResponse만 반환하는 경우 java 복사 편집 @GetMapping("two") public ApiResponse getClients2(ClientSearchRequestDto requestDto) { List clients = clientSearchService.getClients(requestDto.toClientSearchParams()); return ApiResponse.success(new ClientSearchResponseDto(clients)); } ✅ 장점:

코드가 간결해지고 가독성이 좋아진다. @RestController가 붙어 있으면 Spring이 자동으로 객체를 JSON으로 변환하여 응답으로 내려준다. Spring의 기본 응답 처리 (@ResponseBody)를 따르므로 특별한 응답 제어가 필요 없을 때는 더 단순하게 사용할 수 있다. ❌ 단점:

HTTP 응답 상태 코드를 직접 제어할 수 없다. (예: 예외가 발생하면 Spring이 기본적으로 500을 반환함) 클라이언트는 항상 200 응답을 받지만, 내부의 ApiResponse.code 값이 400, 500 등일 수 있어 클라이언트가 추가적으로 응답을 해석해야 한다.

=====

개인적으로 느끼기에 가장 큰 장점은 HttpServletResponse를 직접 조작하지 않고, 간결하게 http 응답을 제어할 수 있다.

===========

ResponseEntity를 사용해야 하는 추가적인 이유 기본적으로 ResponseEntity<ApiResponse>를 사용하면 HTTP 상태 코드 조작이 가능하다는 점이 가장 큰 장점이지만, 이외에도 여러 가지 이유로 ResponseEntity를 사용하는 것이 유리한 경우가 있다.

1. HTTP 응답 헤더를 설정할 수 있음 ResponseEntity를 사용하면 응답 헤더를 추가하거나 변경할 수 있다.

java 복사 편집 @GetMapping(“/download”) public ResponseEntity downloadFile() { Resource file = new FileSystemResource("example.pdf");

1
2
3
4

return ResponseEntity.ok()
    .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=example.pdf")
    .contentType(MediaType.APPLICATION_PDF)
    .body(file); } ✅ 헤더 설정이 필요한 경우 (예: 파일 다운로드, 쿠키 설정)에는 ResponseEntity가 필수적이다.

1. 응답 본문 없이 상태 코드만 반환 가능 일반적으로 ApiResponse 같은 DTO를 사용하면 응답 본문(body)이 항상 포함되어야 한다. 하지만 ResponseEntity를 사용하면 본문 없이 상태 코드만 보낼 수도 있다.

java 복사 편집 @DeleteMapping(“/{id}”) public ResponseEntity deleteResource(@PathVariable Long id) { resourceService.delete(id); return ResponseEntity.noContent().build(); // HTTP 204 No Content 응답 } ✅ 204 No Content 같은 응답을 보낼 때 유용함.

1. 다양한 HTTP 상태 코드와 메시지를 유연하게 처리 가능 ResponseEntity를 사용하면 단순한 성공/실패 응답뿐만 아니라, 다양한 상태 코드와 메시지를 유연하게 처리할 수 있다.

java 복사 편집 @GetMapping(“/{id}”) public ResponseEntity<ApiResponse> getResource(@PathVariable Long id) { Optional resource = resourceService.findById(id);

1
2
3
4
5
6

if (resource.isPresent()) {
    return ResponseEntity.ok(ApiResponse.success(resource.get()));
} else {
    return ResponseEntity.status(HttpStatus.NOT_FOUND)
        .body(ApiResponse.error(HttpStatus.NOT_FOUND.value(), "Resource not found"));
} } ✅ 동적 상태 코드 반환이 필요할 때 적절하다.

1. 예외 처리와의 통합이 용이 전역 예외 처리 (@ExceptionHandler)와 함께 사용하면, HTTP 상태 코드와 메시지를 통일성 있게 관리할 수 있다.

java 복사 편집 @ExceptionHandler(ResourceNotFoundException.class) public ResponseEntity<ApiResponse> handleNotFound(ResourceNotFoundException ex) { return ResponseEntity.status(HttpStatus.NOT_FOUND) .body(ApiResponse.error(HttpStatus.NOT_FOUND.value(), ex.getMessage())); } ✅ 예외 처리와 결합하면 API 응답의 일관성을 유지할 수 있다.

1. 캐시 및 리다이렉션 처리 가능 ResponseEntity를 사용하면 클라이언트의 캐싱을 유도하거나, 특정 URL로 리다이렉트할 수도 있다.

java 복사 편집 @GetMapping(“/redirect”) public ResponseEntity redirect() { return ResponseEntity.status(HttpStatus.FOUND) .location(URI.create("https://example.com")) .build(); } }