👷 @Valid로 쉽게 구현하는 스프링 부트 유효성 검사

클라이언트 요청 값을 서비스 로직에서 if 문으로 하나씩 검사하면 검증 코드가 비즈니스 로직과 뒤섞이고, 컨트롤러마다 비슷한 코드가 반복된다.

Spring Boot에서는 @Valid와 Bean Validation을 사용하여 DTO에 검증 규칙을 선언하는 것만으로 잘못된 요청을 컨트롤러 진입 전에 걸러내고, 일관된 형식의 에러 응답을 반환할 수 있다.

1. Bean Validation 의존성 추가

Spring Boot 2.3부터 유효성 검사 기능이 spring-boot-starter-web에서 분리되었다. @Valid 기반 검증을 사용하려면 spring-boot-starter-validation 의존성을 추가해야 한다.

[Gradle]

// build.gradle
dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-validation'
}

[Maven]

// pom.xml
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

이 스타터에는 Jakarta Bean Validation 표준 API와 구현체인 Hibernate Validator가 포함되어 있어 별도 설정 없이 바로 사용할 수 있다.

Spring Boot 3.x부터는 javax.validation 대신 jakarta.validation 패키지를 사용한다.

2. DTO에 검증 제약 조건 선언

클라이언트 요청을 받을 DTO 필드에 검증 규칙을 어노테이션으로 선언한다.

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Pattern;
import jakarta.validation.constraints.Positive;​
import jakarta.validation.constraints.Size;

import lombok.Getter;
import lombok.NoArgsConstructor;

@Getter
@NoArgsConstructor
public class CommentCreateRequest {
  @NotNull(message = "postId는 필수입니다.")
  @Positive(message = "postId는 1 이상이어야 합니다.")
  private Long postId;
  
  // null 허용
  private Long parentId;
  
  @NotBlank(message = "닉네임을 입력하세요.")
  @Size(max = 10, message = "닉네임은 최대 10자입니다.")
  private String nickname;
  
  @NotBlank(message = "비밀번호를 입력하세요.")
  @Pattern(regexp = "^\\d{4}$", message = "비밀번호는 4자리 숫자여야 합니다.")
  private String password;
  
  @NotBlank(message = "댓글 내용을 입력해주세요.")
  @Size(max = 250, message = "댓글은 최대 250자까지 입력할 수 있습니다.")
  private String content;
}

필수값 검증 어노테이션 비교

@NotNull, @NotEmpty, @NotBlank는 모두 필수 값을 검증하지만 빈 문자열과 공백 문자열을 다루는 방식이 다르다.

문자열 필수 값에는 공백 입력까지 막는 @NotBlank를 주로 사용한다.

범위 / 형식 검증 어노테이션

값의 크기, 범위, 형식, 시점을 제한할 때는 필드 타입에 맞는 어노테이션을 선택한다.

이 어노테이션들은 null을 유효한 값으로 판단한다. 값이 반드시 있어야 하는 필드라면 @NotNull이나 @NotBlank를 함께 선언한다.

3. 컨트롤러에서 @Valid로 검증 실행

DTO에 제약 조건을 선언해도 그 자체로는 검증이 실행되지 않는다. 컨트롤러 메서드 파라미터에 @Valid를 붙여야 Spring이 요청 데이터를 검증하며, 주로 @RequestBody / @ModelAttribute와 함께 사용한다.

@PostMapping
public CommentCreateResponse createComment(
    @Valid @RequestBody CommentCreateRequest request
) {
    // ...컨트롤러 로직
}

요청이 들어오면 Spring은 요청 데이터를 DTO로 바인딩한 뒤 Bean Validation을 수행한다. 제약 조건을 하나라도 위반하면 컨트롤러 메서드가 실행되기 전에 예외가 발생한다.

4. @Valid로 중첩 객체와 컬렉션 검증

Bean Validation은 기본적으로 객체의 직접 필드만 검사한다. DTO 안에 다른 객체가 있거나 컬렉션 요소까지 검사해야 한다면 검증 범위를 명시적으로 넓혀야 한다.

중첩 DTO 검증

DTO 안에 다른 DTO가 있다면 해당 필드에 @Valid를 붙여 검증을 하위 객체로 전파한다.

@Getter
public class OrderRequest {
    @Valid
    @NotNull
    private AddressRequest address;
}

@Getter
public class AddressRequest {
    @NotBlank
    private String city;
    
    @NotBlank
    private String street;
}

address 필드에서 @Valid를 빼면 AddressRequest의 city, street 검증은 수행되지 않는다. @NotNull은 address 자체가 null인 요청을 막는다.

컬렉션 요소 검증

제네릭 타입 인자에 제약 조건을 선언하면 컬렉션의 각 요소까지 검증할 수 있다. Bean Validation 2.0부터 지원하는 컨테이너 요소 제약(container element constraint) 기능이다.

@Getter
public class PostRequest {
    @NotEmpty
    private List<@NotBlank String> tags;
}

@NotEmpty는 리스트가 null이거나 비어 있지 않은지 검사하고, @NotBlank는 리스트의 각 요소가 null, 빈 문자열, 공백 문자열이 아닌지 검사한다.

5. @Valid 검증 실패 예외 처리

@Valid 검증이 실패하면 요청 데이터를 받는 방식에 따라 다른 예외가 발생한다.

@RequestParam, @PathVariable 같은 단일 값 검증은 @Valid가 아닌 메서드 검증으로 동작하며, 발생하는 예외도 다르다.

예외를 따로 처리하지 않으면 Spring Boot가 400 Bad Request와 기본 에러 응답을 반환한다. 클라이언트에 원하는 형식의 에러 응답을 주려면 이 예외를 직접 처리해야 한다.

BindingResult로 컨트롤러에서 직접 처리

@Valid 파라미터 바로 뒤에 BindingResult를 선언하면 검증이 실패해도 예외가 발생하지 않는다. 대신 오류 정보가 BindingResult에 담기고, hasErrors()로 실패 여부를 확인할 수 있다.

@PostMapping
public ResponseEntity<?> createComment(
    @Valid @RequestBody CommentCreateRequest request,
    BindingResult bindingResult) {
    if (bindingResult.hasErrors()) {
        return ResponseEntity.badRequest().body(bindingResult.getAllErrors());
    }    
    return ResponseEntity.ok().build();
}

간단한 API에서는 빠르게 구현할 수 있지만, 컨트롤러마다 같은 처리 코드가 반복되고 에러 응답 형식을 통일하기 어렵다.

@RestControllerAdvice로 전역 처리

@RestControllerAdvice로 검증 예외를 한곳에서 처리하면 모든 컨트롤러가 같은 형식의 에러 응답을 반환하고, 컨트롤러에서 검증 처리 코드를 없앨 수 있다.

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<?> handleValidationException(
        MethodArgumentNotValidException ex) {
        List<String> errors = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(error -> error.getField() + ": " + error.getDefaultMessage())
            .toList();            
        return ResponseEntity.badRequest().body(errors);
    }
}

Spring 5.3부터 MethodArgumentNotValidException은 BindException을 상속한다. @ModelAttribute 요청의 검증 예외까지 함께 처리하려면 BindException을 핸들러 대상으로 지정한다.