MSA에서 Response Entity와 Response custom class로 응답 통일하기

프로젝트를 진행하면서 다양한 팀원과 클라이언트가 서로 다른 모듈이나 서비스를 사용하게 될 때, 응답 형식이 통일되지 않으면 혼란이 발생할 수 있습니다.
 
특히, 마이크로서비스 아키텍처(MSA)에서는 여러 서비스가 독립적으로 개발되기 때문에, 각 서비스마다 서로 다른 응답 구조를 사용하면 전체 시스템의 일관성을 해칠 수 있습니다. 어떤 프로젝트에서든 통일된 응답 포맷은 클라이언트와 협업하는 팀원 모두에게 명확한 인터페이스를 제공하여 디버깅과 유지보수를 용이하게 만들 수 있습니다.
 
오늘 포스팅에서 소개할 방법 중 하나는 Spring Boot에서 제공하는 ResponseEntity와 함께, 제네릭 커스텀 Response 클래스를 활용하는 것입니다!
 
 

Resposne 객체 생성

아래와 같이 간단하면서도 확장성이 뛰어난 Response 클래스를 utility 모듈에 작성하여 성공, 실패에 따른 응답을 파악할 수 있도록 했습니다.
 

Response custom class

package com.example.module_utility.response;

import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.Getter;

@Getter
@JsonInclude(JsonInclude.Include.NON_NULL)
public class Response<T> {
    private final int status;
    private final String message;
    private final T data;

    public Response(int status, String message, T data) {
        this.status = status;
        this.message = message;
        this.data = data;
    }

    public static <T> Response<T> success(T data) {
        return new Response<>(200, "success", data);
    }

    public static Response<Void> successWithoutData() {
        return new Response<>(200, "success", null);
    }

    public static <T> Response<T> error(int status, String message) {
        return new Response<>(status, message, null);
    }
}

@JsonInclude annotation을 통해 successWithoutData와 error 응답과 같이 data 에 null 이 들어가는 경우, 응답에서 null 이 보이지 않도록 해주었습니다.
 
 
단순 POJO 코드이기 때문에, utility 모듈은 다른 모듈을 실행시킬 때 같이 실행시켜 줄 필요가 없고, 해당 모듈에 대한 의존성만 추가해주면 됩니다.
 

의존성 추가 예시

project(':module-exchange') {
	dependencies {
		implementation project(':module-utility')
        // 기타 필요한 의존성
	}
}

 
 
 

Response Entity

위의 Response 클래스만 사용해도 충분히 일관된 응답 구조를 만들 수 있지만, 여기에 ResponseEntity로 추가로 한 번 감싸는 방법을 채택했습니다.
 
Response Entity까지 사용하는 이유는 HTTP 응답의 상태 코드, 헤더 등 부가적인 정보를 명시적으로 제어하기 위함입니다. 즉, 클라이언트에 전송되는 응답 본문 뿐마누아니라, HTTP 프로토콜 차원에서의 상태 코드나 헤더 설정까지 손쉽게 관리할 수 있습니다.
 
단순한 API에서는 공통 Response 클래스를 단독으로 사용해도 되지만, ResponseEntity와 함께 사용함으로써 보다 명확한 에러 핸들링, 상태 코드 관리 및 확장성을 확보할 수 있습니다.
 
 
 

Response Entity와 Response를 이용한 응답 구현

이전에는 서비스 단에서 Response 객체를 직접 생성하여 반환하는 방식으로 구현했던 적이 있었습니다.

@Service
public class ExchangeService {
    public Response<AccountUpdateResponseDTO> executeTransactionProcess(TransactionDTO transactionDTO) {
        // 비즈니스 로직 처리
        AccountUpdateResponseDTO dto = // ... 로직 결과
        // 서비스 계층에서 바로 Response 객체를 생성하여 반환
        return Response.success(dto);
    }
}

 
그리고 컨트롤러에서는 단순히 이 반환값을 그대로 전달하는 방식이었습니다.

 

@PostMapping("/transactions")
public ResponseEntity<Response<AccountUpdateResponseDTO>> saveTransaction(@RequestBody TransactionDTO transactionDTO) {
    // 서비스 단에서 Response를 생성해서 반환하므로, 컨트롤러는 별도의 응답 구성 로직이 필요 없음
    Response<AccountUpdateResponseDTO> response = exchangeService.executeTransactionProcess(transactionDTO);
    return ResponseEntity.ok(response);
}

 
그러나, 서비스 계층은 비즈니스 로직만 처리하고, 응답 구성과 관련된 처리는 컨트롤러에서 담당하는 것이 관심사의 분리 원칙 및 단일 책임 원칙에 부합합니다.
 

• 관심사의 분리(Separation of Concerns)
  서비스 계층은 비즈니스 로직에 집중해야 합니다. HTTP 상태 코드, 응답 포맷, 헤더 등은 프레젠테이션 계층(컨트롤러)의 책임으로 두어야 합니다.
• 단일 책임 원칙(Single Responsibility Principle)
  서비스 계층이 응답 생성까지 담당하면, 비즈니스 로직과 응답 포맷 설정이라는 두 가지 책임을 동시에 지게 됩니다. 이는 유지보수와 테스트에 불리할 수 있습니다.

 
따라서, 현재는 서비스 단에서는 단순히 Response DTO(예: AccountUpdateResponseDTO)만 반환하고, 컨트롤러에서 이를 받아서 ResponseEntity와 공통 Response 클래스로 감싸서 응답을 구성하도록 변경하였습니다.
 
 
예를 들어, ExchangeController에서는 아래와 같이 구현합니다.

ExchangeController 에서 ResponseEntity와 Response 객체 사용

    @PostMapping("/transactions")
    public ResponseEntity<Response<AccountUpdateResponseDTO>> saveTransaction(@RequestBody TransactionDTO transactionDTO) {
        AccountUpdateResponseDTO accountUpdateResponseDTO = exchangeService.executeTransactionProcess(transactionDTO);
        Response<AccountUpdateResponseDTO> response = Response.success(accountUpdateResponseDTO);
        return ResponseEntity.ok(response);
    }

 
실제 코드에서의 사용 방법은 위와 같습니다.
 
현재는 응답 구성이 단순하여 builder 패턴을 사용하지 않고 정적 팩토리 메서드 방식(Response.success())을 사용하고 있지만, 향후 응답에 헤더나 쿠키 등 추가적인 요소를 세밀하게 제어해야 하는 경우에는 builder 패턴을 도입할 예정입니다.
 
현재 상황에서는, 정적 팩토리 메서드를 사용하는 것이 의미 전달(ok, badRequest 등)과 간결함 측면에서 장점이 있어 이 방식을 사용하고 있습니다.
 
 

응답 예시

Response Entity와 Response 객체를 사용한 응답의 성공 예시는 아래와 같습니다.

{
    "status": 200,
    "message": "success",
    "data": {
        "id": 2,
        "totalValue": 2130.00
    }
}

 
HTTP 상태 코드와 메시지, 그리고 실제 데이터가 명확하게 구분되어 있음을 확인할 수 있습니다.
 
 
 

Global Exception Handler

전역 예외 처리(GlobalExceptionHandler)를 도입하여 모든 예외에 대해 일관된 에러 응답을 반환하도록 구성했습니다. 전역 예외 처리기는 HTTP 요청 처리 과정에서 발생한 예외를 잡아 Response 객체로 변환하여 클라이언트에 전달합니다. 
 

package com.example.module_utility.response;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler
    public ResponseEntity<Response<Void>> handleRuntimeException(RuntimeException e) {

        Response<Void> response =Response.error(500, e.getMessage());
        return new ResponseEntity<>(response,HttpStatus.INTERNAL_SERVER_ERROR);
    }

}

 
이전의 Response class는 단순 POJO 코드였기에 스프링 빈으로 등록될 필요가 없었으나, Global Exception Handler는 @RestControllerAdvice 어노테이션이 붙은 컴포넌트입니다. 이는 스프링 컨테이너에 빈으로 등록되어야만 동작하기 때문에 모듈 간에 컴포넌트 스캔 설정이 제대로 되어 있지 않으면, 해당 빈이 등록되지 않아 예외 처리 로직이 실행되지 않습니다.
 

스캔 설정

@SpringBootApplication(scanBasePackages = {"com.example.module_exchange", "com.example.module_utility"})

 
위와 같이 scan이 필요한 패키지를 명시해 주었습니다.
 
 

응답 예시
 

throw new RuntimeException("잔액 부족: 출금 금액이 계좌 잔액보다 큽니다.");

 
throw로 예외를 던지면, 전역 예외 처리기는 이를 가로채서 다음과 같이 응답합니다
 

{
    "status": 500,
    "message": "잔액 부족: 출금 금액이 계좌 잔액보다 큽니다."
}

 
runtimeException에 해당하는 500 status와 함께 error message가 반환됩니다.
이처럼 Response 객체를 활용하면, HTTP 상태 코드와 메시지가 항상 동일한 구조를 유지하게 되어 클라이언트 측의 파싱이나 에러 핸들링이 한층 수월해집니다. 또한, 추가적인 필드(예: timestamp, 오류 코드 등)를 추후 확장할 때에도 모든 에러 응답에 일관되게 반영할 수 있으므로, 전체 API의 안정성과 가독성이 높아집니다.
 
 
참고
https://woodcock.tistory.com/19