Spring Boot에 데이터 검증 (Validation) 적용하기

오늘은 Spring Boot에서 데이터를 검증하는 방법에 대해 알아보겠습니다. 데이터 검증은 RESTful API 개발에서 클라이언트로부터 입력받은 데이터가 유효한지 확인하는 중요한 과정입니다.

---

1. 데이터 검증이란?

• 데이터 검증(Validation): 클라이언트가 전달한 데이터가 사전에 정의된 조건에 맞는지 확인하는 과정입니다.
• 잘못된 데이터는 비즈니스 로직에 문제를 일으킬 수 있으므로 반드시 검증 과정을 거쳐야 합니다.

---

2. Spring Boot에서 Validation 적용하기

Spring Boot에서는 Java Bean Validation(JSR 380)을 사용하여 데이터 검증을 간단히 구현할 수 있습니다.

(1) Validation 의존성 추가

Spring Boot 프로젝트의 pom.xml 또는 build.gradle 파일에 Validation 의존성을 추가합니다.

Maven

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

Gradle

implementation 'org.springframework.boot:spring-boot-starter-validation'

---

(2) DTO 클래스 생성

DTO(Data Transfer Object) 클래스에 검증 어노테이션을 추가합니다.

import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

public class UserRequest {

    @NotBlank(message = "이름은 필수 입력 항목입니다.")
    private String name;

    @Email(message = "유효한 이메일 주소를 입력하세요.")
    private String email;

    @Size(min = 8, message = "비밀번호는 최소 8자 이상이어야 합니다.")
    private String password;

    // Getter & Setter
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

---

(3) Controller에서 Validation 적용

@Valid 어노테이션을 사용하여 요청 데이터를 검증합니다. 문제가 발생하면 자동으로 예외가 발생합니다.

import jakarta.validation.Valid;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @PostMapping
    public ResponseEntity<String> createUser(@Valid @RequestBody UserRequest userRequest) {
        // 유효성 검사를 통과한 데이터 처리
        return new ResponseEntity<>("User created successfully!", HttpStatus.OK);
    }
}

---

(4) 글로벌 예외 처리

유효성 검사 실패 시 기본적인 에러 메시지를 커스터마이징하기 위해 글로벌 예외 핸들러를 작성합니다.

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import java.util.HashMap;
import java.util.Map;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationExceptions(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(error -> 
            errors.put(error.getField(), error.getDefaultMessage())
        );
        return new ResponseEntity<>(errors, HttpStatus.BAD_REQUEST);
    }
}

---

3. Postman을 이용한 테스트

1. 요청 데이터
   POST /api/users로 다음 데이터를 전송합니다.
2. { "name": "", "email": "invalid-email", "password": "123" }
3. 응답 데이터
   아래와 같은 에러 메시지가 반환됩니다.
4. { "name": "이름은 필수 입력 항목입니다.", "email": "유효한 이메일 주소를 입력하세요.", "password": "비밀번호는 최소 8자 이상이어야 합니다." }

---

4. 주요 검증 어노테이션

• @NotBlank: 빈 문자열을 허용하지 않음
• @NotNull: null 값을 허용하지 않음
• @Size: 문자열의 길이 제한
• @Email: 이메일 형식 검증
• @Min / @Max: 숫자 범위 제한
• @Pattern: 정규식 패턴 적용

---

5. 실습 결과

유효성 검증을 적용함으로써 데이터 입력 단계에서 발생할 수 있는 오류를 사전에 방지할 수 있습니다. 적절한 에러 메시지를 반환하면 사용자 경험(UX)도 개선됩니다.