Spring MVC 요청 유효성 검사 완벽 가이드

Spring MVC의 유효성 검사 방식

Spring MVC에서는 요청 매핑(@RequestMapping) 메소드에 대해 자동으로 유효성 검사를 지원합니다. 이는 자바 빈 검증(Bean Validation)도 포함하며, 요청으로 전달된 객체나 값들의 조건을 쉽게 점검할 수 있습니다.

개별 매개변수 검증과 메소드 검증의 차이점

요청에 전달된 개별 객체(@ModelAttribute, @RequestBody, @RequestPart 등)는 해당 파라미터에 @Valid나 @Validated를 붙이면 단독으로 검증이 가능합니다. 하지만 장식자가 메소드의 파라미터에 직접 제약(@NotNull, @Min 등)을 걸면 전체 메소드에 대한 검증이 실행되어 더 넓은 범위의 오류를 잡을 수 있습니다.

두 가지 주요 예외: MethodArgumentNotValidException vs HandlerMethodValidationException

개별 객체 검증 실패 시에는 MethodArgumentNotValidException이, 메소드 전체 매개변수에 대한 검증 오류가 발생하면 HandlerMethodValidationException이 발생합니다. 두 예외 모두 처리 방식이 거의 유사하나, 전자는 단일 객체 오류이고, 후자는 여러 파라미터 오류에 대한 정보를 제공합니다.

@Valid와 제약 애노테이션의 역할

@Valid 자체는 단순히 내부 객체의 제약 검증을 위해 사용되며, 독립적으로 검사 기능을 제공하지 않습니다. 반면 @NotNull 등과 같은 제약 어노테이션을 직접 파라미터에 적용하면 메소드 검증이 작동합니다. 참고로, @RequestBody나 @ModelAttribute의 required 옵션을 활용해 null 여부도 직접 제어할 수 있습니다.

BindingResult 또는 Errors와의 조합

BindingResult나 Errors 같은 파라미터를 함께 사용하면, 검증 에러가 있을 경우에만 컨트롤러가 실제로 실행됩니다. 만약 이 파라미터와 한 쌍이 아닌 다른 곳에 에러가 발생하면, HandlerMethodValidationException이 즉시 발생합니다.

유효성 검사기(Validator) 설정 방법

유효성 검사기는 글로벌(WebMvc 설정) 또는 로컬(@InitBinder) 방식으로 적용할 수 있습니다. 필요에 따라 여러 종류의 검사기를 함께 사용할 수도 있습니다.

@Validated와 메소드 검증의 주의점

컨트롤러 클래스에 @Validated를 명시하면 메소드 검증이 AOP 프록시를 통해 적용됩니다. 단, Spring Framework 6.1부터 내장된 방식의 메소드 검증을 사용하려면 클래스 수준의 @Validated 애노테이션을 제거해야 합니다.

검증 에러 응답 커스터마이즈

검증 실패시 어떻게 예외가 응답되는지는 MessageSource, 로케일, 다국어 리소스 번들을 조합해 원하는 형태로 세밀하게 조정할 수 있습니다.

검증 예외 직접 처리 및 결과 추출

ResponseEntityExceptionHandler를 상속하거나 @ExceptionHandler, @ControllerAdvice 등의 어노테이션을 활용해 검증 예외를 직접 가로채고 처리할 수 있습니다. HandlerMethodValidationException에는 파라미터별 오류 리스트(ValidationResults)가 들어있으니, 이를 반복하면서 상세 오류 정보에 접근할 수 있습니다.

HandlerMethodValidationException ex = ... ;
ex.visitResults(new HandlerMethodValidationException.Visitor() {
    @Override
    public void requestHeader(RequestHeader requestHeader, ParameterValidationResult result) { /* ... */ }
    @Override
    public void requestParam(@Nullable RequestParam requestParam, ParameterValidationResult result) { /* ... */ }
    @Override
    public modelAttribute(@Nullable ModelAttribute modelAttribute, ParameterErrors errors) { /* ... */}
    @Override
    public other(ParameterValidationResult result) { /* ... */}
});

버전 관리 및 확장된 스프링 에코시스템

Spring MVC 유효성 검사는 프레임워크 버전에 따라 동작 방식 차이가 있을 수 있습니다. Spring Boot, Spring Data, Spring Cloud 등 다양한 확장 모듈과도 연계하여 활용 가능합니다.

출처 및 참고 : Validation :: Spring Framework