[Spring Boot] Custom Error Code가 필요한 이유와 에러 코드 문서화

프로젝트 개발하던 중 프론트에게 예외 처리 하는 게 힘들다는 연락을 받았다.  

지금까지 백엔드 개발을 하며 예외 처리는 아래와 같이 처리했다. 

 

 

- AppException

@Getter
public class JikgongException extends RuntimeException {

    private final HttpStatus status;
    private final String errorCode;
    private final String errorMessage;

    // ErrorCode 생성자
    public JikgongException(ErrorCode errorCode) {
        super(errorCode.getErrorMessage());
        this.status = errorCode.getStatus();
        this.errorCode = errorCode.getCode();
        this.errorMessage = errorCode.getErrorMessage();
    }

    public JikgongException(HttpStatus status, String errorCode, String errorMessage) {
        super(errorMessage);
        this.status = status;
        this.errorCode = errorCode;
        this.errorMessage = errorMessage;
    }
}

 

 

 

- ErrorCode

@Getter
@RequiredArgsConstructor
public enum ErrorCode {
    /**
     * member
     */
    MEMBER_NOT_FOUND(HttpStatus.NOT_FOUND, "회원 정보가 없습니다."),
    ACCESS_TOKEN_EXPIRED(HttpStatus.UNAUTHORIZED, "만료된 access token 입니다."),
    REFRESH_TOKEN_EXPIRED(HttpStatus.UNAUTHORIZED, "만료된 refresh token 입니다."),
    REFRESH_TOKEN_NOT_MATCH(HttpStatus.FORBIDDEN, "유효하지 않은 refresh token 입니다. 다시 로그인하세요."),
    MEMBER_PHONE_EXIST(HttpStatus.CONFLICT, "이미 등록된 핸드폰 번호입니다."),
	// ...
    
    /**
     * 알림
     */
    NOTIFICATION_NOT_FOUND(HttpStatus.NOT_FOUND, "알림 정보가 없습니다."),
	// ...
    
    
    /**
     * 좋아요
     */
    LIKE_NOT_FOUND(HttpStatus.NOT_FOUND, "좋아요 누른 정보가 없습니다."),
    LIKE_REQUEST_INVALID(HttpStatus.BAD_REQUEST, "좋아요는 기업이 노동자에게 누를 수 있습니다."),
    LIKE_ALREADY_EXIST(HttpStatus.CONFLICT, "해당 회원에겐 이미 좋아요를 눌렀습니다."),

    /**
     * 이미지, 파일, 경력 증명서
     */
    FILE_NOT_FOUND_EXTENSION(HttpStatus.BAD_REQUEST, "확장자를 찾을 수 없습니다."),
	
    // ...
    
    private final HttpStatus status;
    private final String errorMessage;
}

 

 

 

- ExceptionHandler

@ExceptionHandler(JikgongException.class)
public ResponseEntity<?> handleCustomException(JikgongException e) {
    log.error("핸들링한 에러 발생");
    ErrorResponse errorResponse = ErrorResponse.builder()
        .status(e.getStatus())
        .code(e.getErrorCode())
        .errorMessage(e.getErrorMessage())
        .build();
    return ResponseEntity.status(e.getStatus()).body(new Response<>(errorResponse, "커스텀 예외 반환"));
}

 

 

 

- ErrorResponse

@Builder
@Getter
public class ErrorResponse {

    private HttpStatus status;
    private String errorMessage;
}

 

커스텀한 예외 클래스를 만들고, status와 message는 Enum으로 관리하는 방식의 예외 처리이다. 많은 분들이 이런식으로 예외처리를 하고 계신데, 한 가지 아쉬운 점은 Http Status Code가 400, 401, 403 404, 409, 500 등이 있는데, 하나의 request에서 동일한 code의 예외가 발생한다면 상태 코드만으론 에러를 구분하기가 쉽지 않다.  

 

 

 

만약 회원을 등록하기 위해선 고유한 loginId, 고유한 phone number이 필요하다 가정해보자. 아마 에러 응답은 아래와 같이 반환될 것이다.

// response
{
    "status" : HttpStatus.CONFLICT
    "message" : "이미 등록된 핸드폰 번호입니다."
}

 

 

 

이때 status를 활용한 예외 처리는 동일한 status를 갖는 에러가 여러 개 발생할 수도 있기 때문에 아래와 같이 예외를 구분하는 것은 좋지 못하다.

if (response.errorCode == 409)

 

 

그렇다면 message로 구분해야 하는데 message는 언제든 변경될 수 있고 유지보수 측면에서 봤을 때도 좋지 못하다. 

 

 

 

 

이를 해결하기 위해 아래와 같이 커스텀 에러 코드를 추가해주었다. 

@Getter
@RequiredArgsConstructor
public enum ErrorCode {
    /**
     * member
     */
    MEMBER_NOT_FOUND(HttpStatus.NOT_FOUND, "MEMBER-001", "회원 정보가 없습니다."),
    ACCESS_TOKEN_EXPIRED(HttpStatus.UNAUTHORIZED, "MEMBER-002", "만료된 access token 입니다."),
    REFRESH_TOKEN_EXPIRED(HttpStatus.UNAUTHORIZED, "MEMBER-003", "만료된 refresh token 입니다.").
    
    ...
    
    private final HttpStatus status;
    private final String code;
    private final String errorMessage;
}

 

나는 [도메인]-[Code] 방식으로 커스텀하게 코드를 구성했는데, 각자 원하는데로 하면 될 것 같다.

 

 

이렇게 만든 Custom Error Code는 노션 등을 이용해 따로 문서화 해 클라이언트 개발자와 공유해야한다. 또 추가되거나 수정될 경우에도 업데이트 해줘야한다.

 

굉장히 비효율적이기 때문에 swagger 처럼  자동으로 문서화 시켜주려 이것저것 찾아봤었다. 

 

 

많이 보였던 방식이 RestDocs에 문서화를 하는 방식이었다. 

Custom .Snippet file, 응답값 형식과 형식에 맞는 Descriptor 구현, 그리고 Custom .Snippet file과 Descriptor들을 지정할 Custom Response 클래스 등이 필요하다. 

 

또 이렇게 만들어진 내용에 Test코드까지 작성해야한다. 

 

이미 RestDocs를 사용하고 있으시다면 이런 방식도 괜찮을 것 같은데, 나는 Swagger를 사용하고 있었기 때문에 ㄱ...귀찮았다.

그냥 SSR(타임리프)로 화면을 개발하여 에러 코드 문서화를 시켜줬다. 

 

 - ErrorCodeController

@Controller
public class ErrorCodeController {

    /**
     * 커스텀 에러 코드 문서화를 위한 컨트롤러
     */
    @GetMapping("/error-codes")
    public String getAllErrorCodes(Model model) {
        Map<String, List<ErrorCodeResponse>> groupedErrorCodes = Stream.of(ErrorCode.values())
            .map(errorCode -> new ErrorCodeResponse(
                errorCode.getStatus(),
                errorCode.getCode(),
                errorCode.getErrorMessage()))
            .collect(Collectors.groupingBy(errorCodeResponse -> errorCodeResponse.getCode().split("-")[0]));

        List<ErrorCodeGroup> errorCodeGroups = groupedErrorCodes.entrySet().stream()
            .map(entry -> new ErrorCodeGroup(entry.getKey(), entry.getValue()))
            .collect(Collectors.toList());

        model.addAttribute("errorCodeGroups", errorCodeGroups);

        return "errorCodes";
    }
}

 

ErrorCode 전체를 순회하며 ErrorCodeResponse를 만들어주었고, 도메인별로 묶어 Key, Value 형식의 Map을 생성해주었다.

 

즉 Key가 Member, Value가 List<ErrorCodeResponse>인 Map을 생성해주었고, 이를 model에 담아 넘겨주었다. 

 

 

아래 사진은 다른 분이 RestDocs를 활용하여 구현해두신 커스텀 에러 코드 문서화 페이지이다. 

 

 

 

아래는 내가 타임리프로 구성한 에러 코드 문서 페이지이다. 

 

 

이정도는 지피티가 굉장히.. 잘해준다🤔