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

1. 의존성 추가

Spring Boot 2.3 버전 이후부터는 불필요한 의존성을 줄이기 위해 유효성 검사 기능이 기본 웹 스타터(spring-boot-starter-web)에서 분리되었다. 따라서 @Valid 기반의 Bean Validation을 사용하려면 별도의 의존성을 추가해야 한다.

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

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

해당 스타터에는 Jakarta Bean Validation 표준 API와 이를 구현한 Hibernate Validator가 포함되어 있어 별도의 설정 없이 바로 검증 기능을 사용할 수 있다.

2. 유효성 검사 어노테이션 적용

의존성을 추가한 후에는 클라이언트로부터 전달받을 데이터 객체(DTO)의 필드에 검증 규칙을 어노테이션으로 정의한다.

(참고: Spring Boot 3.x 버전부터는 javax.validation 대신 jakarta.validation 패키지를 사용한다.)

import lombok.Getter;
import lombok.NoArgsConstructor;
​
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Pattern;
import jakarta.validation.constraints.Size;

@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
  null을 허용하지 않는다.
• @NotEmpty
  null과 길이/크기가 0인 값을 허용하지 않는다. (String, 배열, 컬렉션, 맵 등에 적용 가능)
• @NotBlank
  null, 빈 문자열(""), 공백만 있는 문자열을 허용하지 않는다. (String 타입에만 적용 가능)
• @Size(min, max)
  문자열, 배열, 컬렉션 등의 길이/크기를 제한한다.
• @Min(value) / @Max(value)
  지정된 값 이상/이하인지 검증한다. (long, int 등 정수 기반 숫자 타입)
• @DecimalMin(value) / @DecimalMax(value)
  지정한 값 이상/이하인지 검증한다. (BigDecimal, Double 등 소수점 숫자 타입, 값은 문자열로 지정)
• @Positive / @PositiveOrZero
  0보다 크거나(또는 0 이상)인 값을 검증한다.
• @Past / @PastOrPresent
  현재 시점을 기준으로 과거(또는 현재 포함) 날짜인지 검증한다.
• @Future / @FutureOrPresent
  현재 시점을 기준으로 미래(또는 현재 포함) 날짜인지 검증한다.
• @Pattern(regexp)
  정규 표현식을 이용해 문자열 형식을 검증한다. (String 타입에만 적용 가능)
• @Email
  유효한 이메일 형식인지 검증한다.

각 필드의 타입에 따라 적용 가능한 검증 어노테이션과 속성 옵션이 다르므로 데이터의 특성과 비즈니스 요구사항을 고려하여 적절한 제약 조건을 선택하는 것이 중요하다.

특히 문자열, 숫자, 날짜, 컬렉션 등 타입별로 지원하는 어노테이션이 다르기 때문에 단순히 필수값 여부만이 아니라 값의 범위, 형식, 길이, 시점 조건까지 함께 검토해야 한다.

@NotNull, @NotEmpty, @NotBlank 차이

처음 사용할 때 가장 헷갈리는 부분이기 때문에 3가지 어노테이션에 대해 다시 한 번 정리해보자.

@NotNull
1. 모든 타입에 적용 가능
2. 값이 null이 아닌지만 검사
3. 문자열의 경우 빈 문자열("")과 공백(" ")은 허용

@NotEmpty
1. String, 배열, Collection, Map 등에 적용 가능
2. null이 아니고 길이/크기가 0이 아닌지 검사
3. 문자열의 경우 공백(" ")은 허용

@NotBlank
1. String 타입 전용 어노테이션
2. null, 빈 문자열(""), 공백만 있는 문자열 모두 허용하지 않는다.
3. 문자열 필수값 검증 시 가장 많이 사용된다.

@Valid로 중첩 객체 검증

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;
}

Bean Validation은 기본적으로 해당 객체의 직접적인 필드까지만 검사한다. 따라서 중첩 객체의 내부 필드까지 검증하려면 검증이 하위 객체로 전파되도록 @Valid를 명시적으로 선언해야 한다.

만약 OrderRequest에서 address 필드에 @Valid를 붙이지 않으면 AddressRequest 내부의 city, street 필드에 대한 검증은 수행되지 않는다.

컬렉션 내부 요소 검증

컬렉션 자체뿐만 아니라 내부 요소까지 함께 검증할 수 있다.

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

이 문법은 Java 8 이후의 컨테이너 요소 제약 기능이며 @NotEmpty를 통해 리스트가 null이 아니고 비어있지 않은지를 우선 검사하고 @NotBlank를 통해 리스트에 포함된 각 요소가 null, 빈 문자열, 공백 문자열이 아닌지 추가 검증한다.

즉 컬렉션의 구조와 각 요소의 값을 동시에 검증할 수 있다.

3. Controller에 @Valid 적용

DTO에 유효성 검사 어노테이션을 설정한 후에는 실제로 검증이 수행되도록 컨트롤러 메서드의 파라미터에 @Valid를 붙여야 한다.

만약 @Valid를 붙이지 않으면 DTO에 검증 어노테이션이 정의되어 있어도 검증은 수행되지 않는다. 즉 DTO에 제약 조건을 선언하는 것과 실제 검증 실행은 별개의 단계이다.

@Valid는 전달받은 객체에 정의된 제약 조건을 기반으로 요청 데이터가 유효한지 검사하는 역할을 한다. 주로 @RequestBody나 @ModelAttribute와 함께 사용된다.

@PostMapping
public PostCreateResponse createPost(@Valid @RequestBody PostCreateRequest request) {
  // ...컨트롤러 로직
}

클라이언트가 요청을 보내면 Spring이 요청 데이터를 DTO로 바인딩하고 @Valid가 붙어 있다면 Bean Validation을 수행한다. 이때 검증 과정에서 하나라도 제약 조건을 만족하지 못하면 검증이 실패하며 컨트롤러 메서드가 실행되기 전에 예외가 발생한다.

4. 예외 처리

@Valid에 의한 유효성 검사가 실패하면 대표적으로 두 가지 예외가 발생한다.

• @RequestBody로 전달된 DTO의 검증이 실패한 경우
  MethodArgumentNotValidException
• @ModelAttribute 또는 @RequestParam 방식으로 전달된 데이터의 검증이 실패한 경우
  BindException

이 예외를 별도로 처리하지 않으면 Spring이 기본 에러 응답을 반환한다. 하지만 필요에 따라 컨트롤러에서 직접 예외를 처리하거나 @RestControllerAdvice를 활용해 전역에서 공통적으로 처리할 수도 있다.

BindingResult로 직접 처리하는 방법

컨트롤러 메서드에서 @Valid 바로 뒤에 BindingResult를 선언하면 검증 실패 시 예외를 발생시키지 않고 오류 정보를 직접 처리할 수 있다.

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

@Valid가 검증을 수행한 후 검증 실패 시 예외를 던지는 대신 오류 정보를 BindingResult 객체에 저장한다. 이후 bindingResult.hasErrors()를 통해 검증 실패 여부를 확인할 수 있다.

이 방식은 간단한 API에서 빠르게 구현할 수 있다는 장점이 있지만 컨트롤러마다 유사한 검증 처리 코드가 반복될 수 있으며 공통 응답 포맷을 유지하기 어렵다는 단점이 있다.

@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);
  }
}

모든 컨트롤러에서 발생하는 예외를 공통으로 처리할 수 있으며 일관된 에러 응답 포맷을 유지할 수 있어 유지보수 측면에서 유리하다.