공통 응답 자동화 설계 및 구현 (봉투 패턴 도입 - @ResponseBody Advice)

0. 필요성

저번에 했던 6인 프로젝트의 반환 환경 모습이다. 당시 ResultResponse라는 팀 내의 공통 응답 규칙을 정하고, ResponseEntity로 반환하기 전에 DTO를 ResultResponse로 한 번 더 감싸서 반환했다.
그 당시에는 큰 불편함 없이 했던 것 같지만, 다시 보니 2가지 불편 사항이 있었다.

• 1️⃣ 매서드의 반환 타입을 항상 ResponseEntity와 ResultResponse로 감싸줘야 한다. 실제 필자가 프론트 개발자에게 줘야할 JSON 반환 객체는 TokenDTO인데, 그저 반환 규칙을 위해서 프로세스에서는 불필요한 객체를 추가해야만 한다.
• 2️⃣ 같은 이유로 반환값 또한 두 객체를 활용해 감싸줘야 한다.

이는 3인의 백엔드 개발자 중 한 명이라도 실수로 ResultResponse를 활용하지 않으면 공통 응답에서 벗아나는 휴먼 에러를 일으켰다.

그래서 이번 목표는 팀원들이 신경 쓰지 않고, 반환해야할 값 자체를 리턴하면 자동으로 공통 반환 로직에 감싸지도록 만들어보려 한다.

1. 계획

Spring에 요청이 들어와서 처리되는 전반의 과정을 기록해보았다. 여기서 전처리 혹은 후처리 과정이 가능한 곳은 필자가 알고 있는 한에서는 3곳이다.

• 1️⃣ 서블릿 필터 레벨: 서블릿 필터 레벨에서 사용자의 응답을 가로채서 공통 응답 형식으로 변환 처리 후에 다시 돌려주기
• 2️⃣ Interceptor 레벨: postHandle()을 활용해, Controller에서 받은 반환값을 공통 응답 형식으로 변환 처리 후 Handler Adapter에게 돌려주기
• 3️⃣ AOP 레벨: AOP의 @AfterReturning로직을 활용하여 컨트롤러 레이어에서 반환 받은 값에 대해 공통 응답 형식 변환 작업을 해주기

결론부터 말하자면 위의 3가지 과정은 비효율적이거나 불가능해서 활용하지 않았다. 이후 아는 선배의 관련 블로그 글과 GPT를 통해 @ResponseBodyAdvice라는 어노테이션의 존재와 사용법을 알게되었고, 이를 활용했다.
이번 글에서는 (1) 위 3가지 과정이 왜 비효율적이거나 불가능한지 알아보고, (2) @ResponseBodyAdvice의 활용법과 효율성을 말해보겠다.

2. 시도 (1) Servlet Level

public class FilterResponse {

    private final ObjectMapper mapper = new ObjectMapper();

    // Filter 정상 종료에 따른 Response 설정
    public <T> HttpServletResponse ok(HttpServletResponse response, T data)
        throws IOException {

        HashMap<String, Object> responseBody = new HashMap<>();
        responseBody.put("status", "success");
        responseBody.put("message", "성공하였습니다.");
        responseBody.put("data", data);

        response.setContentType("application/json");
        response.setCharacterEncoding("UTF-8");
        response.setStatus(HttpServletResponse.SC_OK);
        response.getWriter().write(mapper.writeValueAsString(responseBody));

        return response;
    }

    public void error(HttpServletResponse response, ErrorCode errorCode) throws IOException {

        HashMap<String, Object> responseBody = new HashMap<>();
        responseBody.put("status", "fail");
        responseBody.put("message", errorCode.getMessage());
        responseBody.put("data", null);

        response.setContentType("application/json");
        response.setCharacterEncoding("UTF-8");
        response.getWriter().write(mapper.writeValueAsString(responseBody));
        response.setStatus(errorCode.getStatus().value());
    }

    public void error(HttpServletResponse response, String msg) throws IOException {
        response.sendError(HttpServletResponse.SC_UNAUTHORIZED, msg);
    }
}

서블릿 레벨에서 공통 응답을 변환해주기 위해서 위와 같이 매소드를 작성했다.

@RequestMapping("/api")
public class UserController {

    private final FilterResponse filterResponse = new FilterResponse();

    @GetMapping("/user")
    public void getUser(HttpServletResponse response) throws IOException {
        User user = new User("John Doe", "johndoe@example.com");
        filterResponse.ok(response, user);
    }
}

모든 응답 값을 해당 공통 응답으로 변환하기 위해서는 컨트롤러 레이어에서 반환값을 바꾸는 필터 매소드를 꼭 호출해야 했다. 배보다 배꼽이 더 커진 경우다. 이렇게 하면 반환 타입에 대한 신경은 써줄 필요가 없지만, Error 시에는 Error Filter Method, 성공 시에는 Success Filter Method를 사용해야 해서 번거로움은 변하지 않았다.

사실 위와 같은 방법은 사용자의 요청이 굳이 Spring MVC까지 갈 필요가 없을 때 자주 활용하는 방식이다. 예를 들기 위해, 저번 프로젝트에서 작성했던 토큰 유효성 체크 로직을 한 번 보겠다.

        // 토큰 유효성 체크 -> 통과 못하면 바로 다음 filter 로 넘어간다.
        switch (jwtUtil.validateToken(token)) {
            case -1:
                request.setAttribute(ConstantUtil.EXCEPTION_ATTRIBUTE, ErrorCode.EXPIRED_TOKEN);
                filterChain.doFilter(request, response);
                return;
            case -2:
            case -3:
            case -4:
                request.setAttribute(ConstantUtil.EXCEPTION_ATTRIBUTE, ErrorCode.INVALID_TOKEN);
                filterChain.doFilter(request, response);
                return;
            case -5:
                filterResponse.error(response, ErrorCode.ALREADY_LOGOUT);
                return;
        }

해당 로직은 AuthFilter 안에 있는 로직으로 case -5:와 같이 이미 로그아웃한 유저의 토큰이면, 그 이후 과정을 거치지 않고 바로 Return 하도록 바꾸었다. 이렇듯 Spring MVC 내부를 들여다보지 않고 필터에서 응답 반환이 가능한 요청에서는 쓰이나 공통 응답 반환을 위해서는 바람직하지 않다.

3. 시도 (2) Interceptor Level

인터셉터는 preHandle()과 postHandle()이라는 전,후처리용 함수를 가지고 있다. 이는 이것을 먼저 활용해 공통 응답 함수를 작성한 선배가 있어 해당 블로그를 참고했다.

결론은 이 방법은 불가능 하다. 이유는 Dispatcher Servlet이 컨트롤러의 응답값 자체를 JSON으로 변환 하기 때문이다. 따라서 인터셉터에서 반환 값 자체를 변환해도 응답 JSON에 영향을 주지 못한다.

4. 시도 (3) AOP 활용

Spring AOP에서도 후처리를 위한 어노테이션이 존재한다. @After 혹은 @AfterReturning이다. @AfterReturning의 경우, 반환 직후 후처리가 가능해서 공통 응답 매소드 활용이 가능할 듯 하다.

하지만 결론은 AOP 또한 공통 응답 포맷 변환이 불가능 하다. 이유는 Interceptor Level과 똑같이 Dispatcher Servlet은 Controller에서 반환한 값 자체만 특정해서 HttpMessageConverter로 변환할 수 있고, AOP가 한 번 변환한 내용을 확인하지 못하기 때문이다. 따라서 필자가 생각했을 땐 다음과 같이 정리할 수 있을 것 같다.

위 그림과 같이 Controller가 값을 반환한 순간 해당 값은 Dispatcher Servlet에게 직행한다. Interceptor와 AOP가 할 수 있는 후처리는 사용자에게 줄 응답에 영향을 주는 후처리가 아니라, 반환 값에 따라 백엔드 Level의 값들에게 영향을 주는 후처리인 것이다.

5. 찾은 방법

3가지 실패로 낙담하던 중 선배의 블로그와 GPT를 통해 @ResponseBodyAdvice를 활용하는 방법을 알게 되었다. 처음에 이름만 듣고 AOP의 일종이라 생각했지만 그것은 아니었고, 그저 특수한 어노테이션이었다.

그렇다면 왜 @ResponseBodyAdvice는 공통응답을 바꿀 수 있을까?

후처리를 위해 태어난 Interceptor와 AOP도 못한 영역이다. 그것이 가능한 이유를 설명하겠다.

@ResponseBodyAdvice가 실행되는 시점은 파란색 체크로 표시한 HtppMessageConverter의 영역이다. 즉 HttpMessageConverter가 컨트롤러의 매서드 반환 값을 JSON으로 변환하기 전에 실행되어 매서드 반환값에 직접 개입한다. 이것이 가능한 이유는 DispatcherServlet에게 일을 위임받은 Handler Adapter가 HttpMessageConverter를 활용해 값을 바꾸기 전에, @ResponseBodyAdvice 구현체를 들여다보고, 해당 컨트롤러의 반환값은 포맷 수정이 필요한지를 확인한다. 만약 형식 변환이 필요한 반환 값이라면, 구현체에 적힌 명세대로 형식을 수정한 뒤 JSON으로 변환한다. 그렇다면 이제 하나씩 코드를 뜯어보면서 확인해보겠다.

(1) 폴더 구조

• 1️⃣ GlobalResponseHandler: @ResponseBodyAdvice 구현체
• 2️⃣ ResultResponse: 팀에서 정한 공통 응답 로직
• 3️⃣ ErrorCode: Enum으로 이루어진 커스텀 에러의 내용물
• 4️⃣ GlobalException : 팀에서 사용할 커스텀 에러, 커스텀 에러는 딱 하나만 두고, 그 내용물을 ErrorCode로 바꾸며 사용할 예정
• 5️⃣ Global Exception Handler: 커스텀 에러가 컨트롤러 레이어 이하 레이어에서 발생하였을 시 어떻게 응답을 던질 건지를 구현한 로직

(2) ResultResponse

@Builder
@Getter
@AllArgsConstructor
public class ResultResponse<T> {    // 제네릭 타입을 클래스 전체에서 사용할 건데, 제네릭 타입을 T라고 명명하겠다.
    private String status;
    private String message;
    private T data;

    // static 함수는 인스턴스 없이 호출되므로, 클래스의 제네릭 타입이 뭔지 확인 불가, 따라서 메서드 내부에서만 사용할 제네릭 타입을 선언 (전부 T라고 했지만, 또 의미도 같지만 명명하는 방법은 달리 해도 됨.)
    // ex - public static<U> ResultResponse<U> success (T data)라고 작성가능
    public static<T> ResultResponse<T> success (T data) {
        return new ResultResponse<>("success", "정상적으로 처리하였습니다.", data);
    }

    public static <T> ResultResponse<T> fail (String message) {
        return new ResultResponse<>("fail", message, null);
    }
}

(3) GlobalResponseHeader

@RestControllerAdvice
public class GlobalResponseHandler implements ResponseBodyAdvice<Object> {

    // 해당 Advice 적용 범위
    @Override
    public boolean supports(MethodParameter returnType,
        Class<? extends HttpMessageConverter<?>> converterType) {
        return true;
    }

    // 응답 변환 매서드
    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType,
        MediaType selectedContentType,
        Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request,
        ServerHttpResponse response) {

        // 만약 반환 타입이 void이면 data 없이 응답
        if (Void.TYPE.equals(returnType.getParameterType())) {
            return new ResultResponse<>("success", "처리가 완료되었습니다.", null);
        }


        // 만약 String이면 예외 발생
        if (body instanceof String) {
            throw new GlobalException(ErrorCode.NOT_ALLOW_STRING);
        }

        if(body instanceof ResultResponse){
            return body;
        }
        return ResultResponse.success(body);
    }
}

위는 이번 구현의 핵심인 @ResponseBodyAdvice 이다. 하나씩 위에서부터 살펴 보자.

1️⃣ @ResponseBodyAdvice 어노테이션의 뜻

ResponseBodyAdvice 인터페이스를 받아서 구현 했다고 해서, 자동 등록이 되지는 않는다. 따라서 Bean 등록을 위해 해당 어노테이션을 저장해두어야 한다. Bean 등록을 해두어야지 싱글톤 패턴이 적용되어, 모든 스레드에서 하나의 ResponseBodyAdvice 객체만을 공유할 수 있다. 이를 하지 않으면 매 요청마다 new GlobalResponseHandler ()를 쓰면서 불러와야 한다.

2️⃣ supports 매소드

    // 해당 Advice 적용 범위
    @Override
    public boolean supports(MethodParameter returnType,
        Class<? extends HttpMessageConverter<?>> converterType) {
        return true;
    }

해당 매소드는 '이 봉투 패턴 도입을 어느 컨트롤러까지 적용할 것인가' 범위를 정하는 함수이다. 필자는 모든 범위에 적용하기 위해 true를 반환했다.

3️⃣ beforeBodyWrite 매소드

    // 응답 변환 매서드
    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType,
        MediaType selectedContentType,
        Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request,
        ServerHttpResponse response) {

        // 만약 반환 타입이 void이면 data 없이 응답
        if (Void.TYPE.equals(returnType.getParameterType())) {
            return new ResultResponse<>("success", "처리가 완료되었습니다.", null);
        }


        // 만약 String이면 예외 발생
        if (body instanceof String) {
            throw new GlobalException(ErrorCode.NOT_ALLOW_STRING);
        }

        if(body instanceof ResultResponse){
            return body;
        }
        return ResultResponse.success(body);
    }

위 매소드는 컨트롤러 반환 값에 대하여 응답 형식 변환을 어떻게 적용할 것인가를 나타내는 매서드이다. 여기서 예외처리 해준 부분은 두 부분이다.

a. 반환 타입이 void이면 ResultResponse(T data)에 들어갈 data라는 인수가 존재하지 않게 된다. 이때 NullPointerException이 날 수 있음으로, type이 void인 경우, 모든 인수를 가진 생성자를 불러서 처리한다.

b. 반환 타입이 String 일 때, 따로 처리해주지 않고, ResultResponse.success(T body)를 쓰면 CastException이 난다. 이유를 알아보면 다음과 같다. String 반환 타입을 가진 Controller에서 String을 반환하는 예시를 들어보자!

a. Controller가 값을 반환하는 시점에 이미 HttpMessageConverter 구현체 중에서 뭘 쓸지 고른다.

b. 이제 컨트롤러 레벨에서 고른 Conveter를 사용하려고 가기 직전에 @ResponseBodyAdvice가 값을 가로채서 String ➜ ResultResponse 객체로 변환한다.

c. 이제 StringHttpMessageConverter를 만나게 되면 Type Cast 에러가 발생한다. 왜냐면 인수로 들어온 값은 객체이기 때문이다. 객체를 JSON 직렬화 하기 위해서는 MappingJackson2HttpMessageConverter가 필요한데, 현재 사용 중인 매소드는 String 직렬화만 가능한 converter이기 때문이다. 따라서 String 반환은 막고, 객체로 답을 출력하도록 유도 해야 한다.

(4) ErrorCode

@Getter
@AllArgsConstructor
public enum ErrorCode {
    MEMBER_NOT_FOUND(HttpStatus.NOT_FOUND, "해당 멤버가 존재하지 않습니다."),
    NOT_ALLOW_STRING(HttpStatus.INTERNAL_SERVER_ERROR, "백엔드 담당자가 String으로 반환을 설정했습니다. String 반환은 허용되지 않습니다. 담당자에게 문의하세요!")
    ;
    private final HttpStatus status;
    private final String message;
    // global (공통)
}

해당 Enum Class는 서비스 내에서 활용한 유일한 커스텀 에러인 Global Exception에 내용물로 사용할 Enum이다. Enum의 구성요소는 status와 message가 되겠다.

(5) Global Exception

@Getter
public class GlobalException extends RuntimeException{
    private final ErrorCode errorCode;

    public GlobalException(ErrorCode errorCode) { this.errorCode = errorCode; }
}

다음은 이번 프로젝트에서 쓰이는 유일한 Custom Exception이다. 모든 에러마다 Custom Exception을 만들어서 관리하는 방법도 있겠으나, 그렇게 해도 오류 내용물만 바뀌는 입장에서 굳이 필요한 절차인지 모르겠다. 그래서 Custom Exception을 하나만 파고, 그것의 내용물을 ErrorCode로 바꿔가며 사요하기로 했다.

(6) Global Exception Handler

import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import spot.spot.global.dto.response.ResultResponse;

@RestControllerAdvice
@RequiredArgsConstructor
public class GlobalExceptionHandler {
    private static final HttpHeaders jsonHeaders;

    static {
        jsonHeaders = new HttpHeaders();
        jsonHeaders.add(HttpHeaders.CONTENT_TYPE, "application/json");
    }
    // 사용자가 예측 가능한 에러 발생 시
    @ExceptionHandler(GlobalException.class)
    public ResponseEntity<ResultResponse<Object>> handleGlobalException ( GlobalException globalException) {
        return ResponseEntity
            .status(globalException.getErrorCode().getStatus())
            .headers(jsonHeaders)
            .body(ResultResponse.fail(globalException.getErrorCode().getMessage()));
    }

    // 예기치 못한 에러 발생 시 (일단 에러 내용이 front 한테도 보이게 뒀습니다. 배포할 때 고치겠습니다.
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ResultResponse<Object>> handleUnExpectException (Exception e) {
        return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .headers(jsonHeaders)
            .body(ResultResponse.fail("서버 내부 오류 발생: " + e.getMessage()));
    }
}

다음은 해당 GlobalException이 났을 떄, 이를 통제할 Exception Handler이다. 일단 미리 jsonHeader를 만들어서 상수로 가지고 있고, ResponseEntity에 사용자가 설정한 에로 코드가 들어갈 수 있도록 했다.
Exception handling 할 상황을 두 가지로 산정했는데, 첫 번째로 개발자가 예측 가능한 혹은 의도한 에러 발생 시 그것을 다루는 @ExceptionHandler(GlobalException.class)이다. 두번째는 개발자가 예측하지 못한 에러 발생 시에 그것을 다루는 @ExceptionHandler(Exception.class)이다 . (필자는 개발 중에 front 쪽에서 error reporting을 해주면 서버를 다시 까서 보는 게 귀찮아서 일단 에러 내용도 같이 반환하도록 해줬다. - 실 배포하면 지워야겠지...)

6. 결과

이제 테스트용 컨트롤러를 짜고 직접 해보자.

    // ✅ 1️⃣ 기본형 반환 (int, double, boolean 등)
    @GetMapping("/primitive")
    public int getPrimitive() {
        return 42; // 자동으로 ResultResponse.success(42)로 감싸져야 함
    }

    // ✅ 2️⃣ 참조형 반환 (String)
    @GetMapping("/string")
    public String getString() {
        return "Spring Boot is running!";
    }

    // ✅ 3️⃣ DTO 객체 반환
    @GetMapping("/dto")
    public SampleDto getDto() {
        return new SampleDto(1, "Test DTO");
    }

    // ✅ 4️⃣ List<T> 반환
    @GetMapping("/list")
    public List<String> getList() {
        return List.of("Apple", "Banana", "Cherry");
    }

    // ✅ 5️⃣ Map<K, V> 반환
    @GetMapping("/map")
    public Map<String, Object> getMap() {
        return Map.of("name", "John", "age", 30, "active", true);
    }

    // ✅ 6️⃣ 예외 발생 테스트 (정의된 예외)
    @GetMapping("/exception")
    public void throwGlobalException() {
        throw new GlobalException(ErrorCode.MEMBER_NOT_FOUND);
    }

    // ✅ 7️⃣ 예기치 않은 예외 테스트 (ArithmeticException)
    @GetMapping("/unexpected-error")
    public void throwUnexpectedError() {
        int result = 10 / 0; // ArithmeticException 발생
    }

    // ✅ 8️⃣ ResponseEntity<T> 직접 반환 (ResponseBodyAdvice가 적용되지 않아야 함)
    @GetMapping("/response-entity")
    public ResponseEntity<SampleDto> getResponseEntity() {
        return ResponseEntity.ok(new SampleDto(2, "ResponseEntity 사용"));
    }

    // ✅ 9️⃣ POST 요청으로 DTO 테스트
    @PostMapping("/post-dto")
    public SampleDto postDto(@RequestBody SampleDto dto) {
        return dto; // 공통 응답으로 감싸져야 함
    }

최대한 모든 유형을 테스트 할 수 있게 해달라고, GPT에 요청해서 코드를 짰다. 코드를 보면 알 수 있듯이 불필요한 ResponseEntity 혹은 공통 응답 형식 (이번 포스팅에서는 ResultResponse)를 매 컨트롤러 반환 타입과 반환값마다 감쌀 필요가 없다.

이제 한 번 테스트를 해볼까?

a. 정상적인 요청 - 정상적인 응답

    @PostMapping("/post-dto")
    public SampleDto postDto(@RequestBody SampleDto dto) {
        return dto; // 공통 응답으로 감싸져야 함
    }

위 함수에 대한 내용이 제대로 나왔다.

b. 정상적이지 않은 요청 - Error 반환

c. 백엔드 개발자가 String을 반환 타입으로 컨트롤러 매서드를 짰을 시, 에러 메시지 반환

String 자체를 반환 하는 경우 Error 메시지를 줘서 DTO 형태로 값을 반환하도록 유도

참고 자료 📚

[[Spring] 스프링 API 공통 응답 포맷 반환 기능을 효율적으로 만들기 ( with ResponseBodyAdvice )

개발 계기 SSAFY 2번째 프로젝트 초기에, 어떤 방식으로 응답을 내보낼 지 회의한 적은 없지만, 다른 백앤드 팀원들이 아래와 같은 방식으로 응답을 내보내는 것을 선호했다. 왜인지는 모르겠지만

whalesbob.tistory.com](https://whalesbob.tistory.com/18)