[Spring Boot] RestControllerAdvice로 Validation Exception 핸들링하기

request 데이터 검증을 위해 Valid, Validation, Spring Boot에서 제공하는 기능을 사용한 경우 Exception이 발생한다. 클라이언트가 데이터를 요청했으나 아무런 안내 없이 에러가 발생한다면 에러의 원인을 알 수 없다. Response에 에러의 원인을 정해진 규격에 맞게 제공하여 클라이언트 작업을 돕고, 데이터를 검증하여 사용할 수 있다.

 

 RestControllerAdvice

• Spring MVC에서 전역적으로 예외 처리를 하는 애너테이션
• @ControllerAdvice와 다른 점은 @ResponseBody를 포함하고 있기 때문에 JSON 형식의 response를 반환함
• 글로벌 예외처리, 사용자 정의 형식의 JSON 구조 반환하는데 사용
• basePackages, basePackageClasses, annotations 속성으로 특정 컨트롤러, 패키지에서 발생하는 예외만 처리하게 할 수 있다
• @Order 애너테이션을 사용해서 controller advice간의 순서를 정할 수도 있다.

@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {

}

• gloabl exception handler에 RestControllerAdvice추가

@Builder
@Getter
public class ErrorResponse {
    private int code;
    private String msg;

    @Builder
    public ErrorResponse(int code, String msg) {
        this.code = code;
        this.msg = msg;
    }
}

 

• Response로 사용하기 위한 객체 추가

예제 코드

Valid, Validation exception 관련 설명은

[Validation] spring boot validation 사용법과 종류

이전 글을 참고하세요!

@Getter
@ToString
@JsonNaming(value = PropertyNamingStrategies.SnakeCaseStrategy.class)
public class RegistBookRequest {
    @Size(min = 1, max = 20, message = "책의 이름은 1~20 자리로 등록해 주세요.")
    private String bookName;

    @NotBlank(message = "카테고리 값은 필수 입니다.")
    private String category;

    @Past(message = "발행일은 과거날짜만 가능합니다. ")
    private LocalDate issuedDay;

    @Max(value = 100, message = "최대로 등록할 수 있는 수량은 100개 입니다.")
    private int amount;
}

@RestController
@RequestMapping("/api/v1/book")
public class BookApiController {
    @PostMapping
    public String regist(
            @RequestBody @Valid RegistBookRequest request
    ) {
        return request.toString();
    }

    @GetMapping("/buy")
    public String buy(
            @RequestParam(name = "book_name") @Size(min = 3, max = 20, message = "책의 이름은 3~20 자리로 등록해 주세요.")
            String bookName,
            @RequestParam(name = "amount") @Max(value = 10, message = "한 번에 최대로 구매할 수 있는 수량은 10개 입니다.")
            int amount
    ) {
        return bookName + " " + amount;
    }
}

 

 

MethodArgumentNotValidException

• @RequestBody 객체의 검증에 실패한 경우 발생하는 에러

// http://localhost:8080/api/v1/book
{
    "book_name": "우리가 빛의 속도로 갈 수 없다면",
    "issued_day": "2023-12-12",
    "amount": 10000
}

 

• 필수 값인 category를 누락시키고 최대 100까지 가능한 amount 값을 초과 시켜 request로 전달

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleMethodArgumentNotValid(MethodArgumentNotValidException ex) {
        List<FieldError> fieldErrors = ex.getBindingResult().getFieldErrors();
        FieldError fieldError = fieldErrors.get(0);
        String field = fieldError.getField(); // amount
        String errorMessage = fieldError.getDefaultMessage(); // 최대로 등록할 수 있는 수량은 100개 입니다.
        Object value = fieldError.getRejectedValue(); // 10000
        String objectName = fieldError.getObjectName(); //registBookRequest

        ErrorResponse response = ErrorResponse.builder()
                .code(ResultCode.NOT_VALID_DATA.getCode())
                .msg(errorMessage + " " + field + "필드의 값 " + value + "를 확인하세요")
                .build();

        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                .body(response);
    }

 

• MethodArgumentNotValidException은 fieldErrors를 통해 validation에 실패한 모든 필드에 대한 정보를 리스트로 제공한다

 

• 유효하지 않은 데이터 검증에 대한 결과를 fieldErrors에서 모두 확인할 수 있음
• fieldError는 검증에 실패한 필드명(getField()), 애노테이션에서 message로 지정한 문자열(getDefaultMessage()), 검증에 실패한 요청 값(getRejectedValue()), RequstBody로 전달 받을 객체의 이름(getObjectName()) 등을 제공한다

{

"code": 40001,

"msg": "카테고리 값은 필수 입니다. category필드의 값 null를 확인하세요"

}

 

• 프론트에서 확인할 수 있도록 메세지를 제공할 수 있다.

ConstraintViolationException

// http://localhost:8080/api/v1/book/buy?book_name=te&amount=11
@RestController
@RequestMapping("/api/v1/book")
@Validated
public class BookApiController {
	@GetMapping("/buy")
    public String buy(
            @RequestParam(name = "book_name") @Size(min = 3, max = 20, message = "책의 이름은 3~20 자리로 등록해 주세요.")
            String bookName,
            @RequestParam(name = "amount") @Max(value = 10, message = "한 번에 최대로 구매할 수 있는 수량은 10개 입니다.")
            int amount
    ) {
        return bookName + " " + amount;
    }
}

 

    @ExceptionHandler(ConstraintViolationException.class)
    public String handleConstraintViolationException(ConstraintViolationException ex) {
        StringBuilder sb = new StringBuilder();
        List<ConstraintViolation> constraintViolations = new ArrayList<>(ex.getConstraintViolations());
        for (ConstraintViolation violation : constraintViolations) {
            sb.append("필드 명 : ").append(violation.getPropertyPath().toString()).append('\n')
                    .append("메세지 : ").append(violation.getMessage()).append('\n')
                    .append("값 : ").append(violation.getInvalidValue()).append("\n\n");
        }
        return sb.toString();
    }

 

필드 명 : buy.bookName 메세지 : 책의 이름은 3~20 자리로 등록해 주세요. 값 : te 필드 명 : buy.amount 메세지 : 한 번에 최대로 구매할 수 있는 수량은 10개 입니다. 값 : 11

 

• 검증에 실패한 모든 필드에 대한 정보를  얻을 수 있음
• method명.field명, defualt message, 검증 실패한 값을 제공

    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<ErrorResponse> handleConstraintViolationException(ConstraintViolationException ex) {
        StringBuilder sb = new StringBuilder();
        ConstraintViolation<?> constraintViolations = ex.getConstraintViolations().iterator().next();

        String errorMessage = constraintViolations.getMessage();
        ErrorResponse response = ErrorResponse.builder()
                .code(ResultCode.NOT_VALID_DATA.getCode())
                .msg(errorMessage)
                .build();

        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                .body(response);
    }

 

{ "code": 40001, "msg": "책의 이름은 3~20 자리로 등록해 주세요." }

 

HandlerMethodValidationException

http://localhost:8080/api/v1/book/buy?book_name=te&amount=11
@RestController
@RequestMapping("/api/v1/book")
//@Validated
public class BookApiController {
    @GetMapping("/buy")
    public String buy(
            @RequestParam(name = "book_name") @Size(min = 3, max = 20, message = "책의 이름은 3~20 자리로 등록해 주세요.")
            String bookName,
            @RequestParam(name = "amount") @Max(value = 10, message = "한 번에 최대로 구매할 수 있는 수량은 10개 입니다.")
            int amount
    ) {
        return bookName + " " + amount;
    }
}

    @ExceptionHandler(HandlerMethodValidationException.class)
    public String handleHandlerMethodValidation(HandlerMethodValidationException ex) {
        List<ParameterValidationResult> results = ex.getAllValidationResults();

        StringBuilder sb = new StringBuilder();
        for (ParameterValidationResult result : results) {
            String value = String.valueOf(result.getArgument());
            String parameterName = result.getMethodParameter().getParameterName();
            String message = result.getResolvableErrors().get(0).getDefaultMessage();
            sb.append(value).append("\n").append(parameterName).append("\n").append(message).append("\n\n");
        }

        return sb.toString();
    }

 

te bookName 책의 이름은 3~20 자리로 등록해 주세요. 11 amount 한 번에 최대로 구매할 수 있는 수량은 10개 입니다.

 

    @ExceptionHandler(HandlerMethodValidationException.class)
    public ResponseEntity<ErrorResponse> handleHandlerMethodValidation(HandlerMethodValidationException ex) {
        ParameterValidationResult results = ex.getAllValidationResults().get(0);

        ErrorResponse response = ErrorResponse.builder()
                .code(ResultCode.NOT_VALID_DATA.getCode())
                .msg(results.getResolvableErrors().get(0).getDefaultMessage())
                .build();

        return ResponseEntity.status(ex.getStatusCode())
                .body(response);
    }

{ "code": 40001, "msg": "책의 이름은 3~20 자리로 등록해 주세요." }

 

HttpMessageNotReadableException

    @ExceptionHandler(HttpMessageNotReadableException.class)
    public ResponseEntity<ErrorResponse> handleReadableException(
            HttpMessageNotReadableException ex,
            HttpServletRequest request
    ) {
        String errorMessage = ex.getMessage(); // JSON parse error: Cannot deserialize value of type `int` from String "한개": not a valid `int` value
        String uri = request.getRequestURI(); // /api/v1/book

        ErrorResponse response = ErrorResponse.builder()
                .code(ResultCode.NOT_VALID_DATA.getCode())
                .msg(errorMessage)
                .build();
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                .body(response);
    }

// http://localhost:8080/api/v1/book

{
    "book_name": "te",
    "category": "철학",
    "issued_day": "2023-12-12",
    "amount": "한개"
}

• amount는 int 타입이어야 하고, 최대로 가질 수 있는 100이 초과하지 않았는지 검증하는 대상
• request시 int로 기대하고 있는 타입을 파싱할 수 없는 String 으로 보내면서 발생한 문제
• exception의 message에서 문제가 발생한 데이터를 안내하고 있으므로 이를 이용

{ "code": 40001, "msg": "JSON parse error: Cannot deserialize value of type `int` from String \"한개\": not a valid `int` value" }