ResponseEntity란 - 개념, 구조, 사용법, 사용하는 이유

ResponseEntity란

Spring Framework에서 제공하는 클래스로, 웹 애플리케이션에서 HTTP 응답을 생성하고 제어하는 데 사용됩니다.

주로 Spring MVC 또는 Spring WebFlux와 함께 사용되며, 클라이언트에게 응답을 반환할 때 응답 본문과 함께 HTTP 상태 코드, 헤더 및 기타 응답 메타 데이터를 포함하는데 유용합니다.

에러 코드와 같은 HTTP상태 코드를 전송하고 싶은 데이터와 함께 전송할 수 있기 때문에 좀 더 세밀한 제어가 필요한 경우 사용한다고 합니다.

 

ResponseEntity의 주요 특징은 다음과 같습니다:

1. HTTP 상태 코드 설정: ResponseEntity를 사용하여 HTTP 응답의 상태 코드를 설정할 수 있습니다. 예를 들어, 성공적인 응답에는 200 OK 또는 다른 성공 상태 코드를 설정할 수 있습니다.

2. 응답 본문 설정: ResponseEntity를 통해 응답 본문의 내용을 설정할 수 있습니다. 이 내용은 JSON, XML, HTML 또는 기타 형식으로 클라이언트에게 반환될 수 있습니다.

3. 응답 헤더 설정: ResponseEntity를 사용하여 응답 헤더를 설정할 수 있습니다. 이로써 특정 헤더(예: Content-Type, Cache-Control 등)를 커스터마이즈하거나 추가할 수 있습니다.

4. 제네릭 타입 지원: ResponseEntity는 제네릭 클래스로 제공되므로, 반환할 데이터의 타입을 명시적으로 지정할 수 있습니다. 이를 통해 Spring은 해당 데이터를 직렬화하여 응답 본문에 적절하게 포함합니다.

ResponseEntity는 다양한 상황에서 사용됩니다. 예를 들어, RESTful 웹 서비스에서 클라이언트에게 JSON 또는 XML 형식의 데이터를 반환하거나, 파일 다운로드를 처리하거나, 사용자 정의 응답 헤더를 설정하는 데 사용됩니다. Spring의 컨트롤러 메서드에서 ResponseEntity를 반환하면 해당 메서드가 요청을 처리하고 응답을 생성하는 데 활용할 수 있습니다.

 

ResponseEntity구조

ResponseEntity는 HttpEntity를 상속받고 사용자의 응답 데이터가 포함된 클래스이기 때문에

HttpStatus       HttpHeaders      HttpBody 

를 포함 합니다.

구현된 인페이스를 살펴보면, body, header, status 순으로 생성자가 만들어진 걸 확인할 수 있습니다.

 

HTTP header 와 body의 차이점

HTTP(하이퍼텍스트 전송 프로토콜)는 웹에서 데이터를 전송하기 위한 프로토콜이며, HTTP 요청과 HTTP 응답이라는 두 가지 주요 형태의 메시지로 구성됩니다. 이 두 가지 메시지는 헤더와 바디라는 두 부분으로 나눌 수 있습니다. 아래에서 HTTP 헤더와 바디의 차이점을 설명하겠습니다.

1. HTTP 헤더:
- 헤더는 HTTP 메시지의 메타 정보를 포함하는 부분입니다.
- 요청 헤더는 클라이언트가 서버에게 요청에 대한 추가 정보를 전달하는 데 사용됩니다. 예를 들어, 브라우저가 서버에게 어떤 종류의 콘텐츠를 원하는지 알려주는 "Accept" 헤더가 있습니다.
- 응답 헤더는 서버가 클라이언트에게 응답과 관련된 정보를 제공하는 데 사용됩니다. 예를 들어, 서버는 응답이 어떤 종류의 콘텐츠인지를 나타내는 "Content-Type" 헤더를 포함할 수 있습니다.
헤더는 키-값 쌍으로 구성되며, 각 키와 그에 대응하는 값은 콜론(:)으로 구분됩니다.

2. HTTP 바디:
- 바디는 HTTP 메시지의 본문 데이터를 포함하는 부분입니다.
- 요청 바디는 클라이언트가 서버에게 전달하려는 데이터를 포함합니다. 이 데이터는 주로 POST 요청 또는 PUT 요청과 같은 HTTP 메서드를 사용하여 서버에게 전송됩니다.
- 응답 바디는 서버가 클라이언트에게 반환하는 데이터를 포함합니다. 이 데이터는 주로 HTML 문서, JSON 데이터, 이미지, 동영상 등 다양한 형식일 수 있습니다.

간단히 말해서, HTTP 헤더는 메시지에 대한 메타 정보를 포함하고, HTTP 바디는 실제 데이터를 포함합니다. 요청과 응답 모두 헤더와 바디를 조합하여 완전한 HTTP 메시지를 형성하며, 이를 통해 클라이언트와 서버 간에 정보 교환과 데이터 전송이 이루어집니다.

 

HTTP 응답 상태 코드(HTTP Response Status Code)는 웹 서버가 클라이언트에게 보내는 HTTP 응답 메시지에 포함된 세 자리 숫자로 된 코드입니다. 이 코드는 클라이언트에게 웹 요청의 결과를 알려주는 역할을 합니다. HTTP 응답 상태 코드는 세 가지 부분으로 구성되며, 각 부분은 의미를 나타냅니다. 일반적으로 다음과 같은 범주에 속하는 상태 코드가 사용됩니다.

1xx (Informational - 정보 전달):

이 범주의 상태 코드는 클라이언트에게 요청이 수신되었으며 처리 중이라는 정보를 전달합니다. 예를 들어, 100 Continue는 클라이언트가 계속 요청을 진행해도 되는지를 확인하기 위해 사용됩니다.

2xx (Successful - 성공):

이 범주의 상태 코드는 요청이 성공적으로 처리되었음을 나타냅니다. 가장 일반적인 상태 코드 중 하나인 200 OK는 요청이 성공적으로 처리되었다는 것을 나타냅니다.

3xx (Redirection - 리디렉션)

이 범주의 상태 코드는 클라이언트가 요청을 완료하기 위해 추가 조치가 필요함을 나타냅니다. 예를 들어, 301 Moved Permanently는 리소스의 위치가 변경되었으며 새 위치로 리디렉션해야 함을 나타냅니다.

4xx (Client Error - 클라이언트 오류)

이 범주의 상태 코드는 클라이언트 측에서 발생한 오류를 나타냅니다. 예를 들어, 404 Not Found는 요청한 리소스를 서버에서 찾을 수 없다는 것을 나타냅니다.

5xx (Server Error - 서버 오류)

이 범주의 상태 코드는 서버 측에서 발생한 오류를 나타냅니다. 예를 들어, 500 Internal Server Error는 서버에서 요청을 처리하는 동안 내부 오류가 발생했음을 나타냅니다.

HTTP 응답 상태 코드는 웹 애플리케이션 및 웹 서비스에서 중요한 역할을 합니다. 클라이언트는 이 코드를 기반으로 요청의 성공 또는 실패를 판단하고 적절한 조치를 취합니다.

HTTP 상태 코드 - HTTP | MDN

 

ResponseEntity 클래스를 사용하는 이유는
결과값, 상태코드,헤더값을 프론트에 넘겨줄 수 있고, 에러코드 또한 섬세하게 설정해서 보내줄 수 있다는 장점이 있습니다.

@RestController
@RequiredArgsConstructor
public class ResponseEntityController {

    private final ResponseEntityService service;

    @GetMapping("/user/{id}")
    public ResponseEntity<MyDto> findByid(@PathVariable Long id) {
        User user = service.getUser();
        MyDto dto = new MyDto();

        HttpHeaders header = new HttpHeaders();
        header.setContentType(new MediaType("application", "json", Charset.forName("UTF-8")));

        dto.setStatus(StatusEnum.OK);
        dto.setData(user);
        dto.setMessage("메세지메세지!");

        return new ResponseEntity<>(dto, header, HttpStatus.OK);
    }
}​

 

ResponseEntity 사용방법

1. HTTP상태 코드 설정

ResponseEntity 객체를 생성하면서 응답의 상태 코드를 명시적으로 지정하면 됩니다. 아래는 HTTP 상태 코드를 설정하는 방법을 보여주는 예제입니다.

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

    @GetMapping("/example")
    public ResponseEntity<String> getExampleData() {
        // 어떤 로직을 통해 데이터를 가져오거나 생성
        String data = "Hello, World!";
        
        // ResponseEntity를 생성할 때 상태 코드를 함께 지정
        return ResponseEntity.status(201).body(data);
    }
}

위의 예제에서는 /example 엔드포인트에 대한 GET 요청을 처리하는 컨트롤러 메서드를 보여줍니다. ResponseEntity.status(201)를 사용하여 HTTP 상태 코드를 201 Created로 설정하고, .body(data)를 사용하여 응답 본문에 데이터를 설정합니다.

HTTP 상태 코드를 설정하는 방법은 다음과 같이 여러 가지 방법이 있습니다:

ResponseEntity.status(HttpStatus.CREATED)를 사용하여 HttpStatus 상수를 사용할 수 있습니다. HttpStatus는 다양한 상태 코드를 미리 정의해 놓은 상수들을 제공합니다.
ResponseEntity.status(200)과 같이 상태 코드의 숫자 값을 직접 지정할 수 있습니다.
상태 코드는 요청에 대한 응답으로 클라이언트에게 특정 상황을 알리는 데 사용됩니다. 적절한 상태 코드를 선택하여 클라이언트에게 올바른 정보를 제공하는 것이 중요합니다.

 

2. 응답 본문 설정

ResponseEntity를 사용하여 응답 본문을 설정하는 방법은 다양한 데이터 형식에 따라 다릅니다. 아래에 몇 가지 일반적인 예제를 제시하겠습니다.

 

2-1. 문자열 응답 본문 설정

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

    @GetMapping("/example")
    public ResponseEntity<String> getExampleData() {
        // 문자열 데이터 생성 또는 가져오기
        String data = "Hello, World!";
        
        // ResponseEntity를 사용하여 문자열 응답 본문 설정
        return ResponseEntity.ok(data);
    }
}

 

2-2. JSON응답 본문설정

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

    @GetMapping("/example")
    public ResponseEntity<MyObject> getExampleData() {
        // JSON으로 직렬화할 데이터 객체 생성 또는 가져오기
        MyObject data = new MyObject("John", 30);
        
        // ResponseEntity를 사용하여 JSON 응답 본문 설정
        return ResponseEntity.ok(data);
    }
}

위의 예제에서 MyObject는 JSON으로 직렬화될 데이터 객체입니다. ResponseEntity.ok(data)를 호출하여 JSON 응답 본문에 해당 데이터를 설정합니다.

 

2-3. 파일 다운로드 응답 설정

import org.springframework.core.io.ByteArrayResource;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

    @GetMapping("/download")
    public ResponseEntity<ByteArrayResource> downloadFile() {
        // 파일 데이터를 바이트 배열로 가져오거나 생성
        byte[] fileData = // ...

        // 파일 다운로드를 위한 ResponseEntity 설정
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_OCTET_STREAM);
        headers.setContentDispositionFormData("attachment", "example.txt"); // 파일 이름 설정

        ByteArrayResource resource = new ByteArrayResource(fileData);

        return new ResponseEntity<>(resource, headers, HttpStatus.OK);
    }
}

위의 예제에서는 파일을 다운로드할 때 ByteArrayResource를 사용하여 파일 데이터를 응답 본문에 설정하고, 

Content-Disposition 헤더를 사용하여 파일 이름을 지정합니다.

ResponseEntity는 다양한 데이터 형식을 응답 본문으로 설정할 수 있으며, 데이터가 어떤 형식인지에 따라 

MediaType와 같은 추가 설정이 필요할 수 있습니다.

 

3. 응답 헤더 설정

ResponseEntity를 사용하여 응답 헤더를 설정하는 방법은 매우 간단합니다. 
ResponseEntity 객체를 생성할 때 응답 헤더를 설정할 수 있습니다. 
다음은 응답 헤더를 설정하는 간단한 예제입니다.

import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

    @GetMapping("/example")
    public ResponseEntity<String> getExampleData() {
        // 응답 본문 데이터 생성 또는 가져오기
        String data = "Hello, World!";
        
        // 응답 헤더 설정
        HttpHeaders headers = new HttpHeaders();
        headers.add("Custom-Header", "Custom-Value");
        
        // ResponseEntity를 사용하여 응답 본문과 헤더 설정
        return ResponseEntity.ok()
            .headers(headers)
            .body(data);
    }
}

 

위의 예제에서는 HttpHeaders 객체를 생성하여 "Custom-Header"라는 사용자 정의 헤더를 추가하고, 
ResponseEntity 객체를 생성할 때 .headers(headers)를 사용하여 응답 헤더를 설정합니다.


응답 헤더를 설정하는 방법에는 다음과 같은 여러 가지 메서드가 있습니다.

headers.add(String headerName, String headerValue)
주어진 이름과 값으로 헤더를 추가합니다.

headers.set(String headerName, String headerValue)
주어진 이름과 값으로 헤더를 설정하며, 동일한 이름의 다른 헤더를 덮어씁니다.

headers.setContentType(MediaType mediaType)
Content-Type 헤더를 설정합니다.

headers.setContentDispositionFormData(String name, String filename)
파일 다운로드 헤더를 설정합니다.

위의 예제에서는 "Custom-Header"를 추가한 것 외에도 HttpHeaders를 사용하여 다양한 헤더를 설정할 수 있습니다. 
필요에 따라 다른 헤더도 설정할 수 있습니다.

 

4. 제네릭 타입 지원

ResponseEntity에서 제네릭 타입을 지원하는 방법은 간단합니다. 
제네릭 타입을 사용하여 ResponseEntity를 생성하고 반환할 때, 반환할 데이터의 타입을 명시적으로 지정하면 됩니다. 
이렇게 하면 Spring은 해당 데이터를 적절한 방식으로 직렬화하여 응답 본문에 포함합니다.

예를 들어, JSON 형식의 데이터를 반환하는 Spring 컨트롤러 메서드를 만들어 보겠습니다.

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

    @GetMapping("/example")
    public ResponseEntity<MyData> getExampleData() {
        // MyData 객체를 생성하거나 데이터를 가져온다고 가정
        MyData data = new MyData("Hello, World!");
        
        // ResponseEntity를 생성할 때 제네릭 타입을 명시적으로 지정
        return ResponseEntity.ok(data);
    }
}

위의 예제에서 MyData는 클라이언트에게 반환하려는 데이터의 타입입니다. 
ResponseEntity.ok(data)를 호출하여 응답을 생성할 때 MyData 객체를 제네릭 타입으로 지정했습니다. 
Spring은 이 데이터를 JSON으로 직렬화하고 응답 본문에 포함합니다. 

이것이 제네릭 타입을 사용하여 ResponseEntity를 생성하는 방법의 간단한 예입니다.

마찬가지로 XML, HTML 또는 다른 데이터 형식을 반환하려면 해당 형식에 대한 클래스를 제네릭 타입으로 지정하면 됩니다. 
Spring은 이를 처리하고 응답을 생성합니다.