[Feat] 전역적 예외 및 핸들러 추가

[helenason]

issue #2

💻 수정 사항

ErrorResponse가 불필요한 정보 없이 필요한 정보만 담도록 하다보니 돌고돌아 저번 프로젝트에서 사용하던 방식이 되었는데요, 다른 방식을 원하신다면 얼마든지 코드 리뷰 남겨주세요!

제가 의도한 사용 예시는 아래와 같습니다.

아래 클래스를 통해 비즈니스 로직에서 발생시킬 예외 코드를 도메인별로 나누어 정의합니다.

@Getter
@AllArgsConstructor
public enum XXXErrorCode implements ErrorCode {

    NOT_FOUND(BAD_REQUEST, "해당 명함이 존재하지 않습니다."),
    INVALID_MEMBER(BAD_REQUEST, "유효하지 않은 사용자입니다."),
    ;

    private final HttpStatus status;
    private final String message;

    @Override
    public ErrorResponse getResponse() {
        return new ErrorResponse(message);
    }
}

그리고 비즈니스 로직에서는 아래와 같이 예외를 발생시킵니다.

public void throwException() {
    throw new BlokException(TestErrorCode.NOT_FOUND);
}

⛳️ 고민 사항

예외 핸들러 구현과 더불어 글로벌 요청/응답 클래스 구현하기를 담당했는데요! 아직 글로벌 요청/응답 클래스를 구현해본 적이 없고, 필요성을 느끼지 못하는 상태라 구현하지 않고 먼저 PR 요청합니다. 제가 이해한 글로벌 응답 클래스는 이러한 것인데, 제가 잘 이해한 게 맞는지 궁금하고, 다른 사례가 있다면 알려주시면 감사하겠습니다 :)

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR. (Beta)
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[Hoya324]

연휴인데 너무너무 수고하셨습니다! 궁금한거 몇 가지 적어두고 가요~!!

[Hoya324]

저는 전 프로젝트에서 @ExceptionHandler(EntityNotFoundException.class) 이런식으로 각 Exception에 대한 예외 Handling을 따로 적용했던거 같은데 어떻게 생각하시는지 궁금합니다!

또한, 중요한 예외의 경우 log도 추가했었는데 저희 컨벤션에 warn 부터는 logging이 되어야한다는 부분이 있어서 이 부분도 고려해봐주시면 좋을거 같아요!
그래서 같은 맥락으로 exception의 이름도 추가하고, timestamp도 추가하면 나중에 logging 시 좋을거 같아서 의견 남겨요!

아래는 제가 생각하는 예시입니다.!!

	@ExceptionHandler(EntityNotFoundException.class)
	public ResponseEntity<ErrorResponse> handleEntityNotFoundException(EntityNotFoundException e) {
		String timestamp = getCurrentTimestamp();
		log.error(LOG_FORMAT, timestamp, e.getClass().getSimpleName(), e.getMessage());
		return ResponseEntity.status(NOT_FOUND)
			.body(ErrorResponse.of(e.getClass().getSimpleName(), NOT_FOUND.value(), e.getMessage()));
	}

[helenason]

1. @ExceptionHandler 파라미터 선언 관련

@ExceptionHandler의 파라미터가 존재하지 않아도 선언한 메서드의 파라미터를 통해 예외 타입을 지정할 수 있는데요! (스프링에서도 메서드 시그니처 파라미터를 통해서만 예외 타입을 지정하여 실수를 방지할 것을 추천하기도 합니다) 저도 마찬가지로 중복 코드를 선호하지 않아서, 파라미터만으로 예외 타입을 선언하도록 하였습니다 :) 이 내용을 기반으로 다시 한번 경호님의 의견을 여쭙습니다!

2. 로그 기준 및 로그에 담을 정보 관련

로그의 경우 컨벤션을 추후 확정하는 것으로 알고 있었어서 기존에는 추가하지 않았었는데요, 로그 관련하여서도 다양한 이야기를 해볼 수 있을 것 같아요! (추후 회의를 통해 명확한 기준을 정하는 것도 좋을 것 같습니다)

1. 개인적으로 예측가능한 예외(ex. 400, 401, 404 등)는 warn보다는 info에 가깝다고 생각해요! 저희가 '대처'해야할 예외가 아닌 클라이언트에게 정보 전달을 위해 직접 '의도'한 예외니까요. 그래서 추후 filter나 interceptor를 통해 로그를 작성하면 되겠다고 생각하고 있었는데요. 이러한 기준과 방법에 대해 어떻게 생각하시는지 궁금합니다!
2. timestamp의 경우는 로그가 발생할 때 아래와 같이 가장 상단에 기본으로 제공되어서 로그에 timestamp를 추가하는 것은 중복이라고 판단하여 제외시켰습니다! 이에 대한 의견도 궁금해요오

2024-10-10 20:35:23 [http-nio-8080-exec-4] INFO  c.z.c.l.config.LoggingInterceptor - LoggingInfoSuccessResponse[identifier=e472b64f-5b04-4ce4-ab08-0c96c43fdd45, httpMethod=GET, uri=/offerings, requestBody=, statusCode=200, latency=238ms]

3. 에러 응답 관련

저는 고민 끝에 아래와 같은 형태로 모든 비즈니스 예외에 대해 BlokException(커스텀 예외)를 반환하도록 하였는데요.

@ExceptionHandler
public ResponseEntity<ErrorResponse> handle(BlokException ex) {
    ErrorCode errorCode = ex.getErrorCode();
    return ResponseEntity
            .status(errorCode.getStatus())
            .body(errorCode.getResponse());
}

경호님이 위에서 제시해주신 예시를 기반으로 저의 의견을 소개드리고 싶어요!

1. response의 body에 status를 포함하는 것은 불필요하다고 생각하였습니다. response의 status를 통해 충분히 제공되는 정보이기 때문에 body에 status를 추가로 포함하는 것은 중복이라고 생각해요!
2. 저는 애플리케이션 단에서 예외를 한가지의 커스텀 예외(BlokException)로 발생시켰기 때문에 response의 body에 exception의 이름을 담는 것이 무의미하다고 판단하였어요! 모든 예외의 이름이 'BlokException'이기 때문에요. 또한, 클라이언트는 서버에서 발생한 예외의 이름을 알 필요가 없다고 생각하기도 하였습니다. 클라이언트에게는 이해하기 쉽게 저희가 예외를 가공하여 전달하는 게 좋은 것 같아요!

---

제가 고민했던 부분들을 경호님이 쏙쏙 짚어주셔서 적다보니 내용이 길어졌는데요 하하 (다음엔 PR description에 고민한 내용을 최대한 적어보겠습니닷..)

불필요한 중복을 최대한 쳐내기 위해 고민 끝에 내린 결론은, 예외를 반환할 때 헤더에 status를 포함하고, 바디에 에러메시지를 포함하자는 결론이었습니다. 하지만 반대로 중복된 정보는 오히려 정보를 얻기 수월하다는 장점이 있을 수 있겠어요. 따라서 애플리케이션 단에서 예외를 발생시킬 방법과, 클라이언트에게 전달할 예외 응답과 관련하여 저희 셋이 논의할 필요가 있어 보여요. 그에 따라 response의 형태도 달라질 것 같아요. 여러분들의 전반적인 의견이 궁금합니다!

[Hoya324]

너무나 친절한 설명 감사드립니다!!
ExceptionHandler, log timestamp, status 모두 결국엔 중복에 대한 고민 결과라고 생각이 들어서 함께 의견 남겨요!
결론적으로는 채영님 의견을 들어보니 충분히 공감되는 부분이라서 그대로 진행해도 좋을거 같다고 생각했어요!

제가 저 exception을 명시하거나 timestamp, status를 과거에 왜 찍었는지 생각했을 때도 결국엔 좀더 관리 측면에서 직관적이라 편하다는 니즈가 있었던거 같아요.
그래서 이 부분은 저희가 진행하다가 필요하면 다시 고민해볼 문제가 맞고 지금은 불필요한 부분 같다는게 채영님의 의견을 듣고 난 후의 생각이었습니다!! 너무나 친절한 설명 조와요~~

[Lim-Changi]

두분께서 충분한 고민을 거쳐 의견을 정리해주셔서 너무 감사드립니다!!

추후 논의를 위한 고민해볼만한 몇 가지 포인트들 한 번 정리해봤어요.

• 에러를 로깅하는 과정에서 중복된 데이터를 제거 및 꼭 필요한 데이터만 첨부

  • 제거했을 때, 응답 사이즈의 차이가 서비스에 어느정도의 영향을 주는지
  • 프론트에서 API 연동 작업을 진행할 때 불편함이 발생하지는 않을지
  • 에러 로깅의 목적 ⇒ 가볍고 중복을 방지하기는 것 보단 최대한 상세한 정보를 담고, 백/프론트 양쪽에서 이슈 트래킹을 원할하도록

• Response Status 에만 상태값을 의지

  • 일부 프론트엔드 프레임워크에서 응답 처리 중 HTTP 상태가 손실되는 케이스 존재

• 공통 에러 클래스를 완벽하게 통일

// 기본 에러 응답
{
  "message": "잘못된 요청 파라미터",
  "timestamp": "2025-02-03T10:30:45Z"
}

// 필드 유효성 검사 상세 에러
{
  "message": "유효성 검사 실패",
  "timestamp": "2025-02-03T10:30:45Z",
  "errors": [
    {
      "field": "email",
      "message": "유효한 이메일 주소여야 합니다",
      "value": "invalid.email"
    },
    {
      "field": "age",
      "message": "0보다 큰 값이어야 합니다",
      "value": "-5"
    }
  ]
}

// 서버 에러 (개발 환경용 디버그 정보 포함)
{
  "message": "내부 서버 오류",
  "timestamp": "2025-02-03T10:30:45Z",
  "error": {
    "code": "SERVER_001",
    "details": "데이터베이스 연결 실패",
    "debug": {
      "exception": "SQLException",
      "stackTrace": "...",
      "correlationId": "cor_abc123"
    }
  }
}

// 요청 제한 초과 에러
{
  "message": "너무 많은 요청",
  "timestamp": "2025-02-03T10:30:45Z",
  "error": {
    "code": "RATE_LIMIT_001",
    "details": "요청 제한 초과",
    "retryAfter": 60,
    "limit": 100,
    "current": 101
  }
}

• 이렇듯 Exception 케이스별로 꼭 담고있어야할 정보가 상이하는 경우가 많고, 동일한 에러 내에서도 다른 필드값을 보고 프론트에서의 에러화면이 달라질 수 있어, 이러한 여러 케이스들을 어떻게 처리하면 좋을지 함께 고민해보면 좋을 것 같습니다!

[helenason]

오 좋은 의견 정말 감사해요!

응답이 많아지면 복잡도가 높아져 클라이언트 입장에서 오히려 읽기 불편할 것이라 생각했다가, 이전에 경호님 코멘트를 받고 변경에 아주 민감한 API응답은 DB 설계할 때와 같이 최대한 변경되지 않도록 세세한 정보를 담는 방향이 더 적절할 수 있다는 생각을 매일같이 하고 있었는데요 ㅋㅋㅋㅋ 찬기님이 주신 다른 근거들을 접하니 더더욱 그렇게 생각하게 되었습니다!! 특히 아래 부분이 인상적이었어요.

에러 로깅의 목적 ⇒ 가볍고 중복을 방지하기는 것 보단 최대한 상세한 정보를 담고, 백/프론트 양쪽에서 이슈 트래킹을 원할하도록

일부 프론트엔드 프레임워크에서 응답 처리 중 HTTP 상태가 손실되는 케이스 존재

이렇게 세세한 정보를 담도록 한다면 에러 응답뿐 아니라 공통 응답 클래스도 더더욱 필요해지겠네요. 첨부해주신 예시 참고해서 코드 수정해보겠습니다 👊

[Hoya324]

이 부분은 공통이라 따로 관리하셨는지 궁금합니다!
그리고 ex.getMessage()로 예외 메시지를 받게 되는건 어떨지, 또는 ErrorCode를 Enum으로 관리해서 status와 message를 관리하는건 어떨지 의견 남겨봐요!

[helenason]

전체 핸들러를 살펴보면 아래와 같은데요!

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler
    public ResponseEntity<ErrorResponse> handle(BlokException ex) {
        ErrorCode errorCode = ex.getErrorCode();
        return ResponseEntity
                .status(errorCode.getStatus())
                .body(errorCode.getResponse());
    }

    // 이곳에 다른 핸들러들이 차근차근 들어올 예정

    @ExceptionHandler
    public ResponseEntity<ErrorResponse> handle(Exception ex) {
        ErrorResponse response = new ErrorResponse("서버 관리자에게 문의하세요.");
        return ResponseEntity
                .internalServerError()
                .body(response);
    }
}

이 부분은 공통이라 따로 관리하셨는지 궁금합니다!

두 메서드 사이에 Validation 예외 등이 나중에 추가될 것이고, 위에서 걸러진 예외가 아닌 다른 모든 예외는 저희가 잡지 못한 예외로 판단하여 가장 아래 메서드인 Exception에서 잡힙니다! 그러한 예상 밖의 예외들은 500에러로 반환하도록 하였어요. 즉, 경호님이 언급주신 위 메서드는 예상치 못한 예외를 잡는 메서드를 의도했다고 봐주시면 됩니다!

그리고 ex.getMessage()로 예외 메시지를 받게 되는건 어떨지, 또는 ErrorCode를 Enum으로 관리해서 status와 message를 관리하는건 어떨지 의견 남겨봐요!

500 에러의 경우는 클라이언트 단이 아닌 서버 단에서 처리할 예외이기 때문에 클라이언트에게는 구체적인 정보를 제공하지 말아야 한다고 생각해요! 하지만 에러코드로 관리하자는 경호님의 의견에 너무나 동의하기 때문에 코드 수정해두었습니다 :)
refactor: 500 서버 에러 코드 추가

+) 또한, 이전 리뷰에서 남겨주신 로그의 warn 레벨은 위와 같은 예상치 못한 예외가 발생하였을 때 로깅하면 좋을 것 같아요! 로그를 어떻게 구성할지 다같이 상의해보고 확정된 내용 바탕으로 추가하겠습니다!

[Hoya324]

오 저는 항상 ErrorCode를 enum으로 관리했어서 이 ErrorCode가 interface인 이유가 궁금해요!!

[helenason]

경호님이 언급해주신, "ErrorCode를 기본 enum 클래스로 관리한다"는 것은 아마 하나의 클래스에서 모든 에러 코드를 관리하는 것으로 이해했는데요!! 제가 ErrorCode를 interface로 선언한 이유는 도메인별로 에러 코드를 분리하자는 의도였습니다!

만약, 저희 도메인이 Card, Member 로 구성되어 있다면 CardErrorCode, MemberErrorCode, (추가로 CommonErrorCode?)로 에러 코드가 분리될 수 있을 거예요! 각 에러 코드는 ErrorCode 인터페이스를 기반으로 구현하면 됩니다!

MemberErrorCode 예시

public enum MemberErrorCode implements ErrorCode {

    INVALID_MEMBER(BAD_REQUEST, "유효하지 않은 사용자입니다."),
    // ...
    ;

    private final HttpStatus status;
    private final String message;

    @Override
    public ErrorResponse getResponse() {
        return new ErrorResponse(message);
    }
}

CommonErrorCode 추가
refactor: 500 서버 에러 코드 추가

[Hoya324]

와 그렇네요!! 이렇게 interface로 에러코드을 추상화하는거 너무 좋습니다👍👍👍

[Lim-Changi]

너무 고생많으셨습니다!!
글로벌 응답 클래스는 이해하신 것 처럼 작업해주시면 될 것 같아요:)

사실 아직 API 가 없어서 완벽하게 Global Response 및 Error 핸들러를 구현하고 테스트해보기 어려울 것 같다는 생각이 드네요ㅠ
일단은 기본적인 부분만 작업해두고, API 에서 저희가 활용해보며 필요한 부분들을 개선해나가는 방향으로 추가 디벨롭이 이루어져도 괜찮을 것 같아요!

이후에 저희 코드상에서 어떻게 쓰이는지 예시도 추가로 만들어 주시면 감사드리겠습니다!!

추가로 Error Response 에 저희가 쓰는 Custom Code 가 있으면 좋을 것 같아요!
⇒ 프론트와 공유하여 에러 상황에 맞는 화면을 더 편하게 구분짓는 목적

[Hoya324]

수고하셨어요!!

[helenason]

@Lim-Changi

1. 넵 노션 페이지에 커스텀 예외 사용 방법 공유해두었습니다! 더 보완할 부분 있으면 말씀해주세요!!

2. 네 좋습니다! 찬기님 의견 반영하여 enum 클래스에서 정의한 이름을 code로 삽입하도록 구현하였습니다!
   feat: 에러 응답에 code 필드를 포함하도록 변경

[helenason]

@Lim-Changi @Hoya324

변경사항

1. 여러 의견 반영하여 최종적으로 공통 성공 응답과 공통 에러 응답을 정의하였습니다. (아래 기술)
2. 기존 GlobalExceptionHandler와 Controller에서 불필요하게 반복되던 ResponseEntity 구현 로직을 제거하기 위해 GlobalResponseHandler를 추가하였습니다.

공통 성공 응답

{
    "status": "CREATED",
    "message": "요청이 성공적으로 처리되었습니다.",
    "timestamp": "2025-02-07T02:20:33.315583",
    "data": {
        "test1": 1,
        "test2": 2,
        "test3": 3
    }
}

관련 클래스: SuccessResponse

컨트롤러에서 SuccessResponse를 반환하면 GlobalResponseHandler가 status와 body를 처리해줍니다.

공통 에러 응답

{
    "status": "BAD_REQUEST",
    "message": "유효하지 않은 사용자입니다.",
    "timestamp": "2025-02-07T01:45:32.235379"
}

관련 클래스: ErrorResponse

GlobalExceptionHandler에서 ErrorResponse를 반환하면 GlobalResponseHandler가 status와 body를 처리해줍니다.

유효성 검증 실패 에러 응답

{
    "errors": [
	  {
              "field": "email",
              "message": "유효한 이메일 주소여야 합니다",
              "value": "invalid.email"
	  },
	  {
              "field": "age",
              "message": "0보다 큰 값이어야 합니다",
              "value": "-5"
	  }
    ],
    "status": "BAD_REQUEST",
    "message": "유효하지 않은 요청값입니다.",
    "timestamp": "2025-02-07T01:46:01.139924",
}

관련 클래스: ValidationErrorResponse

서버 에러 응답

{
    "error": {
        "exception": "NullPointerException",
        "message": "Cannot invoke \"com.evenly.blok.domain.test.controller.TestDto.getTest1()\" because \"test\" is null",
        "stackTrace": "com.evenly.blok.domain.test.controller.TestController"
    },
    "status": "INTERNAL_SERVER_ERROR",
    "message": "서버 관리자에게 문의하세요.",
    "timestamp": "2025-02-07T01:51:00.403302"
}

관련 클래스: ServerErrorResponse

---

더 자세한 내용은 노션에 정리해두었습니다! 추가로 보완할 사항 있으면 편하게 말씀해주세요!

[Hoya324]

너무너무 수고하셨습니다👍👍☺️
고민한 흔적이 많이 있는 작업이었네요!!
저는 친절하게 설명해주신 덕에 더 남길 의견은 없습니다!

[Lim-Changi]

고생하셨어요!! PR 머지해주시면 될 것 같아요 감사합니다:)