[프로젝트] 공통 응답 포맷 설계

PROJECT

공통 응답 포맷 설계

목차

• 1. 배경
• 2. 공통 응답 포맷을 사용하는 이유
• 3. 설계 결정
• 4. 정리

01. 배경

프로젝트 초기 세팅 단계에서 공통 응답 포맷을 설계했다. 수업에서 공통 응답 포맷을 사용하는 방식을 접했고, 직접 적용해보니 일관성 있는 API 응답 구조가 개발 전반에 도움이 된다고 느껴서 이 프로젝트에도 동일하게 적용했다.

02. 공통 응답 포맷을 사용하는 이유

API 응답 형식이 엔드포인트마다 다르면 아래와 같은 문제가 생긴다.

// 어떤 API는 이렇게 반환하고
{ "id": 1, "title": "클린코드" }

// 어떤 API는 이렇게 반환하고
{ "result": "success", "post": { "id": 1 } }

// 에러는 또 이렇게 반환한다
{ "error": "Not Found" }

프론트엔드 입장에서는 API마다 응답 구조가 달라서 처리 코드가 복잡해지고, 백엔드 입장에서도 응답 형식이 통일되지 않아 유지보수가 어려워진다. 공통 응답 포맷을 사용하면 아래 장점이 있다.

• 프론트엔드-백엔드 간 협업 단순화: 모든 API가 동일한 구조를 반환하니까 프론트엔드에서 응답 처리 로직을 하나로 통일할 수 있다.
• 성공/실패 여부를 HTTP 상태 코드에만 의존하지 않아도 됨: success 필드로 명시적으로 표현하면 프론트엔드에서 더 명확하게 처리할 수 있다.
• 에러 메시지 전달 일관화: message 필드로 통일하면 프론트엔드가 에러 메시지를 어디서 꺼내야 할지 매번 확인해야 하는 혼란이 없어진다.
• 확장성: 나중에 메타데이터를 추가하고 싶을 때 ApiResponse<T> 하나만 수정하면 전체 API에 반영된다.

03. 설계 결정

1. ApiResponse<T> — 공통 응답 래퍼

모든 API 응답을 ApiResponse<T>로 래핑해서 성공/실패 여부와 데이터를 일관된 구조로 반환한다. record를 활용해 불변 객체로 설계했다.

/**
서비스 전역에서 사용하는 공통 API 응답 래퍼.
모든 컨트롤러 응답은 이 클래스로 래핑된다.
*/
public record ApiResponse<T>(boolean success, T data, String message) {
    /** 데이터 없는 성공 응답 */
    public static <T> ApiResponse<T> ok() {
        return new ApiResponse<>(true, null, null);
    }
    /** 데이터 있는 성공 응답 */
    public static <T> ApiResponse<T> ok(T data) {
        return new ApiResponse<>(true, data, null);
    }
    /** 실패 응답 */
    public static <T> ApiResponse<T> fail(String message) {
        return new ApiResponse<>(false, null, message);
    }
}

2. record DTO — 불변 데이터 객체

Java 16부터 도입된 record를 DTO에 적극 활용했다. 기존 클래스 기반 DTO 대비 보일러플레이트 코드를 크게 줄일 수 있다. record는 자동으로 생성자, getter, equals(), hashCode(), toString()을 생성해주고 불변 객체라 DTO로 적합하다.

// record 기반 DTO
public record PostResponse(
    Long id,
    String title,
    String author
) { }

3. from() 정적 팩토리 메서드 — DTO 변환 책임 분리

엔티티를 DTO로 변환하는 책임을 DTO 자신이 갖도록 from() 정적 팩토리 메서드를 사용했다. Service는 비즈니스 로직에만 집중할 수 있게 된다.

public record PostResponse(Long id, String title, String author, String genre) {
    /** Post 엔티티를 응답 DTO로 변환한다. */
    public static PostResponse from(Post post) {
        return new PostResponse(
            post.getId(), post.getTitle(), post.getAuthor(), post.getGenre()
        );
    }
}

4. CustomException + ErrorCode — 예외 처리 일관화

예외 발생 시 CustomException과 ErrorCode를 함께 던져 GlobalExceptionHandler에서 일괄 처리한다.

@ExceptionHandler(CustomException.class)
public ResponseEntity<ApiResponse<Void>> handleCustomException(CustomException e) {
    return ResponseEntity
        .status(e.getErrorCode().getStatus())
        .body(ApiResponse.fail(e.getErrorCode().getMessage()));
}

04. 정리

결정	이유
ApiResponse<T> 래퍼	모든 API 응답 형식 통일
record DTO	보일러플레이트 제거, 불변 객체
from() 팩토리 메서드	DTO 변환 책임 분리, Service 단순화
CustomException + ErrorCode	예외 처리 일관화, 전역 핸들링

Last Sync: 2026-04-30 | Booktine Project Log