REST API Response Format에 대한 고찰 (ResponseEntity, JSend, ResponseBodyAdvice)

1) ResponseEntity 사용

HttpStatus, HttpHeaders, HttpBody 데이터를 갖는 ResponseEntity 클래스를 활용한다.

HTTP 응답의 상태 코드, 헤더, 본문을 유연하게 제어할 수 있다.

@GetMapping("/login")
public ResponseEntity<Member> login(String email, String password, HttpServletRequest httpServletRequest) {
    ...
    return new ResponseEntity<Member>(member, httpHeaders, HttpStatus.OK);
}

---

장점

• 유연성이 높다.
  HTTP 응답의 상태 코드, 헤더, 본문을 자유롭게 설정할 수 있다.
• HTTP 표준을 준수한다.
  HTTP 상태 코드를 명확하게 반환하여 표준 HTTP 프로토콜에 맞는 응답을 생성할 수 있다.
• 상태 코드를 명확히 정의한다.
  요청의 성공, 실패, 예외 처리에 따른 상태 코드를 명확하게 정의할 수 있다.
• 간결한 코드
  단순한 경우에 ResponseEntity.ok()나 ResponseEntity.status()로 간결하게 응답을 구성할 수 있다.

단점

• 응답 구조 일관되지 않는다.
  응답 데이터 구조가 일관되지 않을 수 있어, 클라이언트 측에서 다양한 형태의 응답을 처리해야 할 수도 있다.
• 직접 구조를 정의해야 한다.
  성공과 오류에 대해 응답의 구조를 직접 정의해야 하기 때문에 프로젝트 규모가 커질수록 복잡성이 증가할 수 있다.

---

2) JSend

JSend는 웹 서버의 JSON 응답 형식을 지정하는 방법에 대한 몇 가지 규칙을 규정 한 사양이다.

JSON 데이터를 제공하는 많은 웹 서비스가 있고, 각각 고유한 형식의 응답 형식이 있다. 근데, 데이터를 구성하는 데는 공통적인 패턴은 많이 있지만, naming 또는 types of response와 같은 항목에는 약속이 없다.
또한 모든 사람이 서로 상호 작용하는 일반적인 접근 방식을 기대할 수 있기 때문에 상호 간의 통일성을 개선하는데 도움이 된다.

 

JSend는 상태(status), 데이터(data), 메시지(message), 오류 코드(code 등)를 명확하게 구조화한다.

---

장점

• 일관된 응답 구조
  일관된 JSON 응답 구조를 사용하므로, 클라이언트에서 응답 처리 로직을 단순하게 유지할 수 있다.
• 표준화된 오류 처리가 가능하다.
  오류 발생 시 status, message, code 등을 표준화하여 오류를 쉽게 처리할 수 있다.
• 클라이언트에서 예측 가능성 증가한다.
  응답 구조가 항상 같기 때문에 클라이언트가 응답 형식을 예측하고 처리하기 쉽다.

단점

• HTTP 상태 코드와 결합 약해질 수 있다.
  HTTP 상태 코드 대신 status 필드로 상태를 표현하므로, HTTP 상태 코드와의 결합이 약해질 수 있다.
• 유연성이 부족하다.
  HTTP 상태 코드와 헤더를 직접적으로 제어하기에는 한계가 있을 수 있다.
• 추가 구현 필요하다.
  Spring에서 기본 제공되지 않기 때문에 추가적인 구현이 필요하다.

---

JSend 구현

@Getter
@Setter
public class ResponseCommonVo<T> implements Serializable{

    private LocalDateTime timestamp;
    private Integer status;
    private T data;
    private String message;
    
    private ResponseCommonVo() {
    }
    
    private static <T> ResponseCommonVo result(int status, String message, T data) {
        ResponseCommonVo responseCommonVo = new ResponseCommonVo();
        responseCommonVo.status = status;
        responseCommonVo.message = message;
        responseCommonVo.data = data;
        
        return responseCommonVo;
    }
    public static <T> ResponseCommonVo success(T data) {
        return success(200, "OK", data);
    }
    public static <T> ResponseCommonVo fail(String message) {
        return result(0, message, null);
    }
    public static <T> ResponseCommonVo error401(){
        return result(401, "UnAuthorized", null);
    }
    public static <T> ResponseCommonVo error404(){
        return result(404, "Not Found", null);
    }
	
	...
}

 

위와 같이 공통 응답 포맷을 정의하였다.

처음부터 모든 Handler(Controller) 반환값을 ResponseCommonVo로 반환하면 좋겠지만 그렇지 않은 경우도 있고 때에 따라서는 특정한 Handler에서는 적용하지 않아야 할 수도 있을 것이다.

이런 경우 ResponseBodyAdvice를 적용하여 해결할 수 있다.

 

private LocalDateTime timestamp;

timestamp는 ResponseBodyAdvice 구현체에서 공통적으로 설정할 예정이다.

---

ResponseBodyAdvice

ResponseBodyAdvice는 Spring MVC에서 Handler(Controller) 처리 후, 클라이언트로 전달되기 전에 공통적으로 처리하거나 수정하고자 할 때 사용된다.

 

공통 응답 포맷 통일, 데이터 후처리, 보안, 로깅 및 디버깅 등의 경우에 사용 될 수 있다.

ResponseBodyAdvice 인터페이스 파해치기

ResponseBodyAdvice 인터페이스 파해치기