ResponseEntity란?

ResponseEntity란?

 

ResponseEntity는 HTTP 응답을 나타내는 Spring Framework의 클래스이다. 이 클래스는 요청에 대한 응답의 HttpHeader, HttpBody 및 Status Code를 포함하여 클라이언트에게 전달할 수 있는 다양한 기능을 제공한다.

 

아래 코드를 보면, ResponseEntity 클래스는 HttpEntity를 상속받기 때문에 body와 headers를 가질 수 있으며, HTTP 상태 코드를 관리하는 HttpStatusCode를 추가로 포함한다.

 

따라서, ResponseEntity는 HttpStatus, HttpHeaders, HttpBody를 모두 포함하는 객체이며, 이를 통해 HTTP 응답의 상태 코드, 헤더, 본문을 유연하게 구성할 수 있다.

 

HttpStatus

 

HttpStatus는 HTTP 응답에서 서버가 클라이언트의 요청에 대해 어떤 결과를 반환하는지를 나타내는 상태 코드를 의미하며, 여러 상태 코드를 정의하는 열거형(enum) 클래스이다.

 

• 1xx (정보): 요청이 수신되었고, 처리가 진행 중임을 나타낸다.
  • ex) 100 Continue
• 2xx (성공): 요청이 성공적으로 처리되었음을 나타낸다.
  • ex) 200 OK, 201 Created
• 3xx (리다이렉션): 요청이 완료되기 위해 추가 동작이 필요함을 나타낸다.
  • ex) 301 Moved Permanently, 302 Found
• 4xx (클라이언트 오류): 클라이언트의 잘못된 요청을 나타낸다.
  • ex) 400 Bad Request, 404 Not Found
• 5xx (서버 오류): 서버 측에서 요청을 처리하는 도중 오류가 발생했음을 나타낸다.
  • ex) 500 Internal Server Error, 503 Service Unavailable

HttpHeaders

 

HttpHeaders는 HTTP 요청 및 응답에서 메타데이터를 포함하는 헤더 부분을 나타낸다. 헤더는 요청이나 응답에 대한 부가적인 정보를 포함한다.

• Content-Type: 응답 본문의 데이터 타입을 나타낸다. ex) application/json, text/html.
• Authorization: 인증 정보를 포함하는 헤더로, 예를 들어 Bearer token 방식의 인증을 전달할 때 사용된다.
• Cache-Control: 클라이언트에게 응답을 캐시할지 여부 및 기간을 지시하는 헤더
• Set-Cookie: 서버가 클라이언트에 쿠키를 설정할 때 사용하는 헤더
• Location: 리다이렉션할 URL을 나타내며, 보통 3xx 응답과 함께 사용

HttpBody (HTTP 본문)

 

HttpBody는 HTTP 요청 또는 응답의 실제 데이터를 담는 부분이며, 클라이언트와 서버가 주고받는 데이터의 실질적인 내용이 여기에 포함된다.

• 요청 본문: 클라이언트가 서버로 데이터를 전송할 때 사용하는 본문이다. 예를 들어, POST 요청에서 전송되는 JSON 데이터나 파일 업로드의 내용이 본문에 포함된다.
• 응답 본문: 서버가 클라이언트에게 반환하는 데이터로, HTML, JSON, XML, 바이너리 파일 등 다양한 형태가 될 수 있다.

Spring에서는 본문을 직렬화/역직렬화하여 클라이언트와 서버 간에 객체 데이터를 주고받을 수 있다.

 

ResponseEntity의 특징

 

1. HTTP 상태 코드 포함

• ResponseEntity는 HTTP 응답에 대한 상태 코드를 명시적으로 설정할 수 있다. 예를 들어, 200 OK, 404 Not Found, 500 Internal Server Error와 같은 상태 코드를 클라이언트에게 반환할 수 있다.
• 이를 통해 성공, 실패, 잘못된 요청 등의 상황을 클라이언트에게 명확하게 전달할 수 있다.

2. HTTP 헤더 포함

• ResponseEntity는 응답에 HTTP 헤더를 추가할 수 있는데, 이를 통해 캐싱 정보, 인증, 콘텐츠 타입 등 다양한 추가 정보를 클라이언트에게 전달할 수 있다.

3. HTTP 본문 포함

• 응답의 본문(body)을 포함할 수 있어, 데이터를 클라이언트에게 전달할 수 있다. 일반적으로 객체나 문자열을 본문으로 포함하며, Spring은 이를 자동으로 JSON 또는 XML 등으로 직렬화해 클라이언트에 전송한다.

4. 제네릭 타입 지원

• ResponseEntity<T>는 제네릭 클래스로, 응답 본문(body)의 타입을 제네릭 타입 으로 지정할 수 있다. 이를 통해 다양한 데이터 형식을 유연하게 처리할 수 있다.
• 예를 들어, 본문에 문자열, 객체, 리스트 등을 모두 담을 수 있다.

5. 유연한 응답 생성

• ResponseEntity는 다양한 생성자를 제공하여 상태 코드, 본문, 헤더를 각각 설정할 수 있다. 상태 코드만 포함된 응답, 헤더와 상태 코드가 포함된 응답, 본문과 상태 코드가 포함된 응답 등 다양한 조합이 가능하다.

ResponseEntity를 사용함으로써 결과값, 상태코드, 헤더값을 프론트에 넘겨줄 수 있고, 에러코드 또한 섬세하게 설정해서 보내줄 수 있다는 장점이 있기에 Restful 서비스에서 자주 쓰인다.

 

코드 예시

 

다음은 상품 ID를 DB에서 조회하여 해당 ID에 맞는 상품을 가져오는 간단한 코드이다.

 

헤더에는 "TestHeader"와 "TestValue"를 추가하였고, ResponseEntity를 반환할 때 상태 코드는 200으로 설정하였으며, 응답 본문(body)에는 productDto(상품 정보)를 포함시켰다.

@GetMapping(value = "/product/{productId}")
    public ResponseEntity<ProductDto> getProduct(@PathVariable Long productId) {

        long startTime = System.currentTimeMillis();
       
        ProductDto productDto = productService.getProduct(productId);

        LOGGER.info(
                "[getProduct] Response :: productId = {}, productName = {}, productPrice = {}, productStock = {}, Response Time = {}ms",
                productDto.getProductId(),
                productDto.getProductName(),
                productDto.getProductPrice(),
                productDto.getProductStock(),
                (System.currentTimeMillis() - startTime));

        HttpHeaders headers = new HttpHeaders();
        headers.add("TestHeader", "TestValue");

        // return productDto;
        return ResponseEntity.status(200).headers(headers).body(productDto);
    }

 

Swagger를 통해 요청을 보내면, 응답으로 HTTP 상태 코드 200이 반환되며, 응답 본문(body)에는 productDto가 포함된 것을 확인할 수 있다. 또한, 응답 헤더(header)에는 "TestHeader"와 "TestValue"가 추가된 것을 확인할 수 있다.

 

참고

https://padak-padak.tistory.com/entry/ResponseEntity란-개념-구조-사용법-사용하는-이유

[Spring] ResponseEntity란? (tistory.com)