📝 에러 코드 공통화 및 인터페이스 작성

[psychology50]

작업 이유

• 사전에 정의한 Error Document 문서에 대한 인터페이스 생성
• 공통 에러 응답 인터페이스를 통한 예외 응답 메시지 통일화
• 명시적인 주석을 통한 개발 생산성 향상

작업 사항

✒️ 요약

• Base Code가 될 StatusCode, ReasonCode 열거 타입 클래스 작성.
• Common 모듈에서 관심사가 아닌 DomainCode와 FieldCode는 인터페이스화.
  • DomainCode : 도메인 모듈에서 해당 인터페이스를 구현한 하나의 열거 타입 클래스로 관리한다.
  • FieldCode : 각 Domain 별로 해당 인터페이스를 구현한 열거 타입 클래스를 작성하도록 한다.
• 예외에 대한 정보를 담고 있는 CausedBy record 작성
• GlobalExceptionHandler에서 공통 예외를 처리하기 위한 GlobalErrorException 작성
  • 해당 예외를 사용하려는 모든 하위 커스텀 예외 클래스들은 BaseErrorCode를 구현해야 한다.
  • 명시적으로 예외를 구분하기 위해 GlobalErrorException을 상속받을 수 있다.
    • ex. AuthErrorException, DomainErrorException
• 모든 에러는 임의로 생성하지 않고 팀원과 회의한 후 반드시 문서에 기록한다. (중복 에러 제거를 위함)

1️⃣ Base Code : StatusCode

/**
 * HTTP 상태 코드
 */
@Getter
@RequiredArgsConstructor
public enum StatusCode {
    SUCCESS(200),
    CREATED(201),
    NO_CONTENT(204),

    BAD_REQUEST(400),
    UNAUTHORIZED(401),
    FORBIDDEN(403),
    NOT_FOUND(404),
    METHOD_NOT_ALLOWED(405),
    NOT_ACCEPTABLE(406),
    CONFLICT(409),
    PRECONDITION_FAILED(412),
    UNPROCESSABLE_CONTENT(422),

    INTERNAL_SERVER_ERROR(500),
    SERVICE_UNAVAILABLE(503);

    private final int code;
}

• 전체 응답 코드 7bit 중 상위 3bit에 해당하는 상태값에 해당한다.
• 가장 대표적인 14가지 상태값이 포함되어 있다.
• 클라이언트가 애플리케이션 계층에서 상태를 확인 가능하도록 하기 위한 정보.

2️⃣ Base Code : ReasonCode

/**
 * 에러 발생 이유 코드
 */
@Getter
@RequiredArgsConstructor
public enum ReasonCode {
    /* 400_BAD_REQUEST */
    INVALID_REQUEST_SYNTAX(0),
    MISSING_REQUIRED_PARAMETER(1),
    MALFORMED_PARAMETER(2),
    MALFORMED_REQUEST_BODY(3),

    /* 401_UNAUTHORIZED */
    MISSING_OR_INVALID_AUTHENTICATION_CREDENTIALS(0),
    EXPIRED_OR_REVOKED_TOKEN(1),
    INSUFFICIENT_PERMISSIONS(2),
    TAMPERED_OR_MALFORMED_TOKEN(3),

    /* 403_FORBIDDEN */
    ACCESS_TO_THE_REQUESTED_RESOURCE_IS_FORBIDDEN(0),
    IP_ADDRESS_BLOCKED(1),
    USER_ACCOUNT_SUSPENDED_OR_BANNED(2),
    ACCESS_TO_RESOURCE_NOT_ALLOWED_FOR_USER_ROLE(3),

    /* 404_NOT_FOUND */
    REQUESTED_RESOURCE_NOT_FOUND(0),
    INVALID_URL_OR_ENDPOINT(1),
    RESOURCE_DELETED_OR_MOVED(2),

    /* 405_METHOD_NOT_ALLOWED */
    REQUEST_METHOD_NOT_SUPPORTED(0),
    ATTEMPTED_TO_ACCESS_UNSUPPORTED_METHOD(1),

    /* 406_NOT_ACCEPTABLE */
    REQUESTED_RESPONSE_FORMAT_NOT_SUPPORTED(0),

    /* 409_CONFLICT */
    REQUEST_CONFLICTS_WITH_CURRENT_STATE_OF_RESOURCE(0),
    RESOURCE_ALREADY_EXISTS(1),
    CONCURRENT_MODIFICATION_CONFLICT(2),

    /* 412_PRECONDITION_FAILED */
    PRECONDITION_REQUEST_HEADER_NOT_MATCHED(0),
    IF_MATCH_HEADER_OR_IF_NONE_MATCH_HEADER_NOT_MATCHED(1),

    /* 422_UNPROCESSABLE_CONTENT */
    REQUIRED_PARAMETERS_MISSING_IN_REQUEST_BODY(0),
    VALIDATION_ERROR_IN_REQUEST_BODY(1),
    ;

    private final int code;

    @Override
    public String toString() {
        return name();
    }
}

• 사전에 명시한 Error Convention을 따른다.
• 예외 종류에 따라 Domain Code와 Field Code 확인 필요 여부가 다를 수 있다.
• 추가 혹은 수정 및 삭제 예외 항목이 발생할 경우, 팀 회의를 통해 결정하도록 한다.

3️⃣ Base Code : DomainCode

/**
 * 도메인 코드
 * <br>
 * 도메인 코드는 각 도메인별로 고유한 코드를 가지고 있으며, 해당 코드는 각 도메인별로 고유한 에러를 구분하기 위해 사용된다.
 * <br>
 * ZERO(0)는 기본 코드로 사용되며, 도메인 코드를 사용하지 않는 경우에 사용한다.
 * <pre>
 * ZERO 필드는 모든 BaseErrorCode를 구현하는 모든 도메인 코드에서 정의되어야 한다.
 * {@code
 * @RequiredArgsConstructor
 * public enum DomainBitCode implements DomainCode {
 *      ZERO(0),
 *      USER(1),
 *      PRODUCT(2),
 *      ORDER(3);
 *
 *      private final int code;
 *
 *      @Override
 *      public int getCode() {
 *          return code;
 *      }
 *
 *      @Override
 *      public String getDomainName() {
 *          return name().toLowerCase();
 *      }
 * }
 * }
 * </pre>
 * @author YANG JAESEO
 */
public interface DomainCode {
    int getCode();
    String getDomainName();
}

• Domain Code를 구분해야 하는 에러 응답에 필수적으로 포함되어야 한다.
• Domain bit를 사용하지 않는 에러 응답을 위해 반드시 ZERO(0)을 포함한다.
• Domain 모듈에서 해당 인터페이스를 구현하여, Entity bit를 설정한다.

  public enum DomainBitCode implements DomainCode {
      ZERO(0), USER(1), FEED(2), NOTIFICATION(3), ...; // Entity 별로 bit값 결정
  
      private final int code;
      // ... 하위 메서드 추가
  }

4️⃣ Base Code : FieldCode

/**
 * 도메인의 필드 코드
 * <pre>
 * {@code
 * @RequiredArgsConstructor
 * public enum UserFieldCode implements FieldCode {
 *    ZERO(0),
 *    ID(1),
 *    PASSWORD(2),
 *    NAME(3);
 *
 *    private final int code;
 *
 *    @Override
 *    public int getCode() {
 *      return code;
 *    }
 *
 *    @Override
 *    public String getFieldName() {
 *      return name().toLowerCase();
 *    }
 * }
 * }
 * </pre>
 * @author YANG JAESEO
 */
public interface FieldCode {
    int getCode();
    String getFieldName();
}

• Domain 모듈에서 해당 인터페이스를 구현하여, Entity 별로 예외 처리에 필요한 bit값을 설정한다.
• Entity 내의 모든 속성이 포함되지 않을 수 있으며, 표현 가능한 수의 범위를 벗어나는 경우 16진수로 변경될 수 있다.
• bit를 사용하지 않는 에러 응답을 위해 반드시 ZERO(0)을 포함한다.

  public enum UserCode implements FieldCode {
      ZERO(0), NAME(1), USERNAME(2), PASSWORD(3), ...; // Attribute 별로 bit값 결정
  
      private final int code;
      // ... 하위 메서드 추가
  }

5️⃣ CausedBy

/**
 * 에러 코드를 구성하는 상세 코드
 *
 * @param statusCode {@link StatusCode} 상태 코드
 * @param reasonCode {@link ReasonCode} 이유 코드
 * @param domainCode {@link DomainCode} 도메인 코드
 * @param fieldCode {@link FieldCode} 필드 코드
 *
 * - see also: {@link StatusCode}, {@link ReasonCode}, {@link DomainCode}, {@link FieldCode}
 */
public record CausedBy(
    StatusCode statusCode,
    ReasonCode reasonCode,
    DomainCode domainCode,
    FieldCode fieldCode
) {
    private static final int STATUS_CODE_MULTIPLIER = 10000;
    private static final int REASON_CODE_MULTIPLIER = 1000;
    private static final int DOMAIN_CODE_MULTIPLIER = 10;

    public CausedBy {
        Objects.requireNonNull(statusCode, "statusCode must not be null");
        Objects.requireNonNull(reasonCode, "reasonCode must not be null");
        Objects.requireNonNull(domainCode, "domainCode must not be null");
        Objects.requireNonNull(fieldCode, "fieldCode must not be null");

        if (!isValidCodes(statusCode.getCode(), reasonCode.getCode(), domainCode.getCode(), fieldCode.getCode())) {
            throw new IllegalArgumentException("Invalid bit count");
        }
    }

    /**
     * CausedBy 객체를 생성하는 정적 팩토리 메서드
     * <br/>
     * 모든 코드의 조합으로 생성된 최종 코드는 7자리의 문자열로 구성된다.
     * @param statusCode {@link StatusCode} 상태 코드 (3자리)
     * @param reasonCode {@link ReasonCode} 이유 코드 (1자리)
     * @param domainCode {@link DomainCode} 도메인 코드 (1자리 or 2자리)
     * @param fieldCode {@link FieldCode} 필드 코드 (1자리)
     * @throws IllegalArgumentException 전체 코드가 7자리가 아닌 경우, 혹은 각 상태 코드가 자릿수를 준수하지 않은 경우
     * @throws NullPointerException 인자가 null인 경우
     * @return CausedBy
     */
    public static CausedBy of(StatusCode statusCode, ReasonCode reasonCode, DomainCode domainCode, FieldCode fieldCode) {
        return new CausedBy(statusCode, reasonCode, domainCode, fieldCode);
    }

    /**
     * status code, reason code, domain code, field code를 조합하여 에러 코드를 생성한다.
     * @return String : 7자리 정수로 구성된 에러 코드
     */
    public String getCode() {
        return generateCode();
    }

    /**
     * 에러가 발생한 이유를 반환한다.
     * <br/>
     * Reason은 사전에 예외 문서에 명시한 정보를 반환한다.
     * @return String : 에러가 발생한 이유
     */
    public String getReason() {
        return reasonCode.name();
    }

    private String generateCode() {
        return String.valueOf(statusCode.getCode() * STATUS_CODE_MULTIPLIER + reasonCode.getCode() * REASON_CODE_MULTIPLIER + domainCode.getCode() * DOMAIN_CODE_MULTIPLIER + fieldCode.getCode());
    }

    private boolean isValidCodes(int statusCode, int reasonCode, int domainCode, int fieldCode) {
        return isValidDigit(statusCode, 3) && isValidDigit(reasonCode, 1) && (isValidDigit(domainCode, 1) || isValidDigit(domainCode, 2)) && isValidDigit(fieldCode, 1);
    }

    private boolean isValidDigit(int number, long expectedDigit) {
        return calcDigit(number) == expectedDigit;
    }

    private long calcDigit(int number) {
        if (number == 0) return 1;
        return Stream.iterate(number, n -> n > 0, n -> n / 10)
            .count();
    }
}

• 공통 예외를 발생시키는 인터페이스에 담아야 하는 예외 정보 항목.
• 클라이언트에게 반환하기 위한 예외 응답 코드 7bit 정보를 담고 있다.
• 속성 중 하나라도 null이 들어오면 NPE가 발생한다.
• 전체 code 조합 문자열이 7자리를 만족하지 않는 경우, 혹은 각 필드 중 하나라도 자릿수를 준수하지 않는 경우 IllegalArgumentException이 발생한다.
  • statusCode : 언제나 3자리 정수값을 갖는다.
  • reasonCode : 언제나 1자리 정수값을 갖는다.
  • domainCode : 1자리 혹은 2자리 정수값을 갖는다.
  • fieldCode : 언제나 1자리 정수값을 갖는다.
• CausedBy 객체를 생성할 때는 생성자 혹은 정적 팩토리 메서드를 사용한다.

  CausedBy causedBy = new CausedBy(...);
  // 혹은
  CausedBy causedBy = CausedBy.of(...);

6️⃣ BaseErrorCode

/**
 * 커스텀 에러 코드를 정의하기 위한 인터페이스
 * <br>
 * 에러 코드는 다음과 같은 형식으로 정의한다.
 * <br>
 * <pre>
 * {@code
 * @Getter
 * @RequiredArgsConstructor
 * public enum UserErrorCode implements BaseErrorCode {
 *      NOT_FOUND_EMAIL(StatusCode.NOT_FOUND, ReasonCode.ACCESS_TO_THE_REQUESTED_RESOURCE_IS_FORBIDDEN, FieldCode.EMAIL, "해당 유저의 이메일이 존재하지 않습니다."),
 *      NOT_FOUND_USER(StatusCode.NOT_FOUND, ReasonCode.ACCESS_TO_THE_REQUESTED_RESOURCE_IS_FORBIDDEN, FieldCode.ZERO, "해당 유저가 존재하지 않습니다."),
 *
 *      REQUIRED_EMAIL(StatusCode.UNPROCESSABLE_CONTENT, ReasonCode.REQUIRED_PARAMETERS_MISSING_IN_REQUEST_BODY, FieldCode.EMAIL, "이메일은 필수 입력값입니다."),
 *
 *      private final StatusCode statusCode;
 *      private final ReasonCode reasonCode;
 *      private final FieldCode fieldCode;
 *      private final String message;
 *
 *      @Override
 *      public CausedBy causedBy() {
 *          return CausedBy.valueOf(statusCode, reasonCode, DomainCode.USER, FieldCode.COMMON);
 *      }
 *
 *      @Override
 *      public String getExplainError() throws NoSuchFieldError {
 *          return message;
 *      }
 * }
 * }
 * </pre>
 * 에러 코드는 다음과 같은 형식으로 사용한다.
 * <pre>
 * {@code throw new GlobalErrorException(UserErrorCode.NOT_FOUND_USER); }
 * </pre>
 * See Also:
 * {@link CausedBy}, {@link StatusCode}, {@link ReasonCode}, {@link DomainCode}, {@link FieldCode}, {@link GlobalErrorException}
 * @author YANG JAESEO
 */
public interface BaseErrorCode {
    CausedBy causedBy();
    String getExplainError() throws NoSuchFieldError;
}

• GlobalErrorException으로 예외를 던지기 위한 커스텀 예외가 반드시 구현해야 하는 인터페이스
• 2가지 메서드로 구성되어 있다.
  • causedBy() : 예외 정보인 CausedBy 객체를 반환하는 메서드
  • getExplainError() : 에러 로그 혹은 클라이언트 측에 에러 이유를 설명하기 위한 메서드.
• 해당 인터페이스를 구현하는 모든 커스텀 예외는 반드시 두 가지 메서드를 구현해야 한다.
• explainError의 용도는 추후 팀 회의를 통해 명확히 하도록 한다.
  • 클라이언트에게 반환하는 메시지가 될 경우, 예외 문서를 확인하지 않아도 에러 이유를 확인 가능하도록 명시적인 에러 문구를 작성한다.
  • 서버에서 로깅을 위한 정보가 될 경우, 에러 발생 경로와 사유 등을 구체적으로 명시하도록 한다.

7️⃣ GlobalErrorException

/**
 * 전역 에러 처리를 위한 예외 클래스
 * <br>
 * 전역 에러 처리를 명시적인 에러 처리로 변경하고 싶다면 다음과 같이 사용한다.
 * <pre>
 * {@code
 * public class DomainErrorException extends GlobalErrorException {
 *    private final DomainErrorCode errorCode;
 *
 *    public DomainErrorException(DomainErrorCode errorCode) {
 *      super(errorCode);
 *      this.errorCode = errorCode;
 *    }
 *
 *    public CausedBy causedBy() { return errorCode.causedBy(); }
 *    public BaseErrorCode getErrorCode() { return errorCode; }
 * }
 * }
 * </pre>
 * @author YANG JAESEO
 */
@Getter
public class GlobalErrorException extends RuntimeException {
    private final BaseErrorCode baseErrorCode;

    public GlobalErrorException(BaseErrorCode baseErrorCode) {
        super(baseErrorCode.causedBy().reasonCode().name());
        this.baseErrorCode = baseErrorCode;
    }

    public CausedBy causedBy() {
        return baseErrorCode.causedBy();
    }

    @Override
    public String toString() {
        return "GlobalErrorException(code=" + baseErrorCode.causedBy().getCode()
                + ", message=" + baseErrorCode.getExplainError() + ")";
    }
}

• 추후 @RestControllerAdvice를 통해 전역 에러를 핸들링하기 위한 예외 객체.
• BaseErrorCode를 구현하는 모든 커스텀 에러가 공통적으로 사용 가능하다.
• 명시적으로 에러를 발생시키는 이유를 구분하고 싶다면, 해당 클래스를 상속한다.
  • AuthErrorException
  • DomainErrorException
  • 기타 등등.

리뷰어가 중점적으로 확인해야 하는 부분

• 전체적인 흐름 파악 및 사용법을 이해하였는지?
• CausedBy의 Compact Constructor 내 예외 처리가 타당한지?
• 이보다 더 나은 인터페이스 설계 방식이 존재하는지?
• BaseErrorCode를 구현하는 커스텀 예외 클래스에서 다룰 explainError의 사용처에 대한 아이디어 필요.
• 추가 테스트가 필요한 케이스가 존재하는지?

발견한 이슈

• 다들 바쁜 관계로 일단 혼자 임의로 에러 코드 컨벤션 정하고 인터페이스 만든 거라, 추후 회의 후 재조정될 수 있음.

🟡 테스트 코드 추가
총 6가지 테스트를 수행하였고, 정상적으로 통과했음을 확인했습니다.

1. 모두 정상적인 인자로 생성할 수 있음을 확인한다.
2. null 인자로 생성할 수 없음을 확인한다.
3. 상태 코드(3), 이유 코드(1), 도메인 코드(2), 필드 코드(1)가 아니면 생성할 수 없음을 확인한다.
4. 생성된 코드가 예상값과 일치하는 지 확인한다.
5. 두 자리 수의 도메인 코드가 예상값과 일치하는 지 확인한다.
6. 에러가 발생한 올바른 이유를 반환한다.

[psychology50]

다시 확인해보니 CausedBy 클래스 범위 주석에 있는 see also 항목은 필요없을 거 같네요.

[jinlee1703]

에러 코드에 대한 테스트까지 작성해주실 줄 몰랐는데, 고생 많으셨습니다!

[asn6878]

이렇게 상세한 에러코드를 생성하는 방법은 처음봐서 놀랐습니다!
많이 배워갑니다~