[구현 기록] CustomException + ErrorCode 구조 설계

BACKEND

CustomException + ErrorCode 구조 설계

목차

• 1. 배경
• 2. 전체 구조
• 3. ApiResponse — 공통 응답 래퍼
• 4. ErrorCode — 에러 중앙 관리
• 5. CustomException — 비즈니스 예외
• 6. GlobalExceptionHandler — 전역 예외 처리
• 7. 실제 동작 흐름
• 8. 정리

Spring Boot 프로젝트에서 예외 응답 형식을 통일하기 위해 CustomException, ErrorCode, GlobalExceptionHandler 구조를 설계했다.

1. 배경

Spring Boot 프로젝트에서 예외 처리를 별도로 설계하지 않으면 여러 문제가 생긴다.

• 서비스 레이어마다 예외 처리 방식이 달라진다.
• 에러 메시지를 문자열로 직접 작성하면 오타가 생기거나 일관성이 깨진다.
• 클라이언트에 전달되는 에러 응답 형식이 제각각이 된다.
• 어떤 에러가 어디서 발생했는지 추적하기 어렵다.

Booktine에서는 이 문제를 해결하기 위해 모든 에러 응답을 ApiResponse 형식으로 통일하고, 도메인별 예외를 한 곳에서 관리하는 구조를 설계했다.

2. 전체 구조

네 가지 클래스가 역할을 나눠 담당한다.

클래스	역할
ApiResponse	성공/실패 응답을 통일된 형식으로 래핑
ErrorCode	HTTP 상태코드 + 메시지를 enum으로 중앙 관리
CustomException	ErrorCode를 감싸는 RuntimeException
GlobalExceptionHandler	예외를 캐치해 ApiResponse로 변환

Service에서 예외 발생 → CustomException(ErrorCode) → GlobalExceptionHandler 캐치 → ApiResponse.fail() 응답

3. ApiResponse — 공통 응답 래퍼

모든 API 응답에 사용하는 공통 래퍼다. Java record로 정의해 불변 객체로 관리한다.

ApiResponse는 성공/실패 응답 형식을 하나로 통일하기 위해 사용했다. 프론트엔드에서는 success 여부만으로 응답 상태를 일관되게 처리할 수 있다.

세 가지 정적 팩토리 메서드로 사용한다.

• ok(data) — 데이터가 있는 성공 응답
• ok() — 데이터 없는 성공 응답
• fail(message) — 에러 메시지를 담은 실패 응답

컨트롤러에서는 아래와 같이 사용한다.

// 데이터 반환
return ResponseEntity.ok(ApiResponse.ok(postService.getPost(postId)));

// 데이터 없는 성공
return ResponseEntity.ok(ApiResponse.ok());

// 에러 응답은 GlobalExceptionHandler에서 자동 처리

컨트롤러는 데이터를 직접 반환하지 않고 ApiResponse로 감싸 반환한다. 이 구조 덕분에 모든 API 응답 형식이 동일하게 유지된다.

4. ErrorCode — 에러 중앙 관리

도메인 전반의 에러를 HTTP 상태코드와 메시지를 묶어 enum으로 정의했다.

public enum ErrorCode {
    // 공통
    INVALID_INPUT(400, "잘못된 입력입니다."),
    UNAUTHORIZED(401, "인증이 필요합니다."),
    FORBIDDEN(403, "접근 권한이 없습니다."),

    // 사용자
    USER_NOT_FOUND(404, "사용자를 찾을 수 없습니다."),
    DUPLICATE_EMAIL(409, "이미 사용 중인 이메일입니다."),
    INVALID_PASSWORD(400, "비밀번호가 일치하지 않습니다."),

    // 커뮤니티
    COMMUNITY_POST_NOT_FOUND(404, "커뮤니티 게시글을 찾을 수 없습니다."),
    COMMUNITY_LIKE_ALREADY_EXISTS(409, "이미 좋아요를 누른 게시글입니다."),
    COMMUNITY_REPLY_DEPTH_EXCEEDED(400, "대댓글에는 대댓글을 작성할 수 없습니다."),

    // 진행률/목표
    MONTHLY_GOAL_ALREADY_EXISTS(409, "해당 월의 월간 목표가 이미 존재합니다."),

    // 서버
    INTERNAL_SERVER_ERROR(500, "서버 내부 오류가 발생했습니다.");

	// .. 등등
    private final int status;
    private final String message;
}

상태코드와 메시지를 enum으로 관리해 문자열 오타나 중복 정의 문제를 줄일 수 있었다.

상태코드와 메시지를 한 곳에서 관리하기 때문에 새로운 에러가 생기면 ErrorCode에만 추가하면 된다. 도메인별로 ErrorCode를 분리하는 방식도 있지만, 현재 Booktine 규모에서는 단일 파일 구조가 더 단순하다고 판단했다.

5. CustomException — 비즈니스 예외

ErrorCode를 멤버로 가지는 RuntimeException이다.

CustomException은 ErrorCode를 감싸는 역할만 담당한다. 서비스 레이어에서는 ErrorCode만 넘겨주면 된다.

서비스 레이어에서는 아래와 같이 사용한다.

// 존재하지 않는 리소스 조회
User user = userRepository.findById(userId)
        .orElseThrow(() -> new CustomException(ErrorCode.USER_NOT_FOUND));

// 중복 검사
if (userRepository.existsByEmail(email)) {
    throw new CustomException(ErrorCode.DUPLICATE_EMAIL);
}

// 권한 검사
if (!post.getUser().getId().equals(userId)) {
    throw new CustomException(ErrorCode.FORBIDDEN);
}

문자열 대신 ErrorCode를 사용하기 때문에 예외 처리 흐름이 훨씬 명확해졌다.

6. GlobalExceptionHandler — 전역 예외 처리

@RestControllerAdvice로 전역에서 예외를 캐치하고 ApiResponse 형식으로 응답한다.

예외 응답 형식을 전역에서 통일하기 위해 GlobalExceptionHandler를 사용했다.

7. 실제 동작 흐름

사용자가 존재하지 않는 게시물을 조회하는 경우를 예시로 보면 다음과 같다.

예외 처리 흐름
요청이 들어오면 Controller는 Service를 호출한다. Service에서 정상 처리에 성공하면 ApiResponse.ok()를 반환하고, 예외가 발생하면 CustomException이 발생한다. 발생한 예외는 GlobalExceptionHandler가 전역에서 처리한 뒤, 최종적으로 ApiResponse.fail() 형태의 응답으로 변환되어 클라이언트에 전달된다.

클라이언트에는 아래 형식으로 실패 응답이 내려간다.

{
  "success": false,
  "data": null,
  "message": "게시물을 찾을 수 없습니다."
}

성공 응답은 아래 형식이다.

{
  "success": true,
  "data": { ... },
  "message": null
}

8. 정리

이 구조의 핵심은 역할 분리다.

• 서비스 레이어는 예외를 던지는 것만 담당한다.
• GlobalExceptionHandler는 응답 변환만 담당한다.
• ErrorCode는 에러 정의만 담당한다.

새로운 에러가 필요하면 ErrorCode에 한 줄 추가하고 throw new CustomException(ErrorCode.XXX) 형태로 던지면 끝이다.

예외 응답 형식이 달라지면 GlobalExceptionHandler 한 곳만 수정하면 된다. 이 구조 덕분에 예외 처리 흐름이 단순해지고 응답 형식도 일관되게 유지된다.