[Spring] ResponseEntity

들어가기 전에

ResponseEntity 는 HttpEntity 를 상속받는 클래스로, 멤버변수로 HttpStatus 객체를 포함한다. 즉, API 로 클라이언트에게 응답할 때 HTTP 상태 코드와 HTTP 헤더를 함께 원하는 데이터를 전송할 수 있게 돕는 클래스이다.

HttpStatus 클래스

HttpStatus 클래스에 대해 알아보기 전에, HTTP 에서 전달되는 정보에는 무엇이 있는지 살펴보겠다.

 

HTTP 상태 코드 목록

간단하게 5개의 범위에서 상태 코드는 반환된다.

1. 응답의 상태에 대한 정보를 전달 (예: 응답이 아직 진행중 - 102 Processing) (100 – 199)
2. 성공적인 응답 (200 – 299)
3. 리디렉션을 요청하는 응답 (300 – 399)
4. 클라이언트의 오류 (요청할 때 잘못되었음) (400 – 499)
5. 서버의 오류 (서버 내부에서 오류 발생함) (500 – 599)

 

HTTP 헤더

HTTP 헤더는 요청이나 응답에 대한 추가적인 정보를 전달할 때 사용된다. 바디에 담기지 않는 정보들이 헤더에 담긴다.

헤더는 사용되는 맥락에 따라 아래와 같이 4개로 분류될 수 있다:

• 요청 헤더들(Request Headers)
  • 조회를 요청하는 자원에 또는 요청하는 주체인 클라이언트에 대한 추가적인 정보를 포함한다.
• 응답 헤더들(Response Headers)
  • 응답의 위치 또는 응답을 제공하는 서버에 대한 정보와 같은 추가 정보를 포함한다.
• 상징 헤더들(Representation Headers)
  • 자원의 MIME (문서, 파일의 포맷과 같은 정보를 나타냄) 종류를 포함한다.
  • 인코딩/압축 적용 여부를 포함한다.
  • 위 두개와 같이 자원의 바디로 요청/응답되는 내용에 대한 추가 정보를 포함한다.
• 페이로드 헤더들(Payload Headers)
  • 정보의 표현과 상관 없는 운반과 관련된 정보들을 포함한다.
  • 내용의 길이와 정보 운반을 위해 사용되는 인코딩 정보를 포함한다.

---

ResponseEntity 클래스

ResponseEntity 클래스에는 HTTP 상태 코드와 헤더를 설정할 수 있는 메서드들이 있다.

 

ResponseEntity 의 활용

먼저, ResponseEntity 는 스프링 MVC 의 컨트롤러 (@Controller) 의 메서드들의 반환 타입으로 사용될 수 있다.

다음 컨트롤러를 보자:

    @PostMapping("/new")
    public ResponseEntity<HospitalResponse> addNewHospital(@RequestBody HospitalRequest hospitalRequest) {
        HospitalResponse savedHospital = hospitalService.addNewHospital(hospitalRequest);
        return ResponseEntity.ok().body(savedHospital);
    }

여기서 컨트롤러는 서비스에 정의된 addNewHospital() 메서드를 활용해 @RequestBody 로 받은 HospitalRequest DTO 를 테이블에 저장한다. 이 메서드의 반환 타입은 ResponseEntity<HospitalResponse> 로, HospitalResponse 의 내용을 반환하되, ResponseEntity 로 감싸 HTTP 상태 코드도 함께 반환할 수 있다.

위에서 사용된 메서드 ok() 와 body() 는 다음과 같은 의미를 가지고 있다:

 

• ok(): HTTP 상태코드 200으로, 성공적으로 요청과 응답이 이루어졌다는 것을 의미한다.
• body(T object): HTTP 바디 즉 전달되어야 하는 내용을 설정해주는데, 타입은 T 이다.
  위 예시에서는 ResponseEntity<HospitalResponse> 로 타입을 설정했기 때문에 T = HospitalResponse 이다.

 

이외에도 ResponseEntity 의 스태틱 메서드 중 몇 개를 소개하자면 다음과 같다.

 

• created(URI location): HTTP 상태 코드 201, CREATED 로 설정되며, 주어진 URI로 헤더에 위치 정보를 추가한다.
• getStatusCode(): HTTP 상태 코드가 무엇인지를 반환한다.
• status(int status): HTTP 상태 코드를 주어진 status 로 설정한다.

 

이들은 객체 생성시 사용되는 builder를 생성하여 상태 코드 또는 헤더를 설정한다.

 

출처

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

HTTP response status codes - HTTP | MDN

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#response_context

HTTP headers - HTTP | MDN

https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/ResponseEntity.html

ResponseEntity (Spring Framework 6.0.2 API)