Spring Boot 시리즈 4편 – @Valid 입력값 검증과 글로벌 예외 처리 전략

B컷개발자 2025. 4. 17. 19:28

728x90

Spring Boot에서 @Valid를 활용한 입력값 검증과 글로벌 예외 처리 방법을 정리했습니다. 실무에서 자주 쓰이는 검증 패턴과 ControllerAdvice 전략까지 안내합니다.

Spring Boot 시리즈 4편 – @Valid 입력값 검증과 글로벌 예외 처리 전략

API 개발에서 입력값 검증은 보안성과 안정성의 시작점입니다.
이번 편에서는 Spring Boot 환경에서 @Valid, @Validated, @ControllerAdvice 등을 활용해 입력값 검증과 예외 처리 구조를 체계적으로 구성하는 방법을 설명하겠습니다.

🧪 1. 입력값 검증을 왜 해야 할까?

클라이언트가 비정상적인 데이터를 보낼 수 있음
비즈니스 로직 이전에 잘못된 데이터는 차단해야 함
일관된 에러 응답 포맷 제공은 API 신뢰도 향상에 필수

🧱 2. DTO 클래스에 유효성 검증 애노테이션 적용

public class UserDto {

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

    @Email(message = "이메일 형식이 올바르지 않습니다.")
    @NotBlank
    private String email;
}

주요 검증 애노테이션

애노테이션 설명

@NotBlank	null, 빈 문자열 모두 허용하지 않음
@Email	이메일 형식 유효성 체크
@Size	문자열 또는 리스트의 길이 제한
@Min, @Max	숫자 범위 제한

📬 3. Controller에서 @Valid 적용

@PostMapping
public ResponseEntity<UserDto> createUser(@Valid @RequestBody UserDto userDto) {
    userService.createUser(userDto);
    return ResponseEntity.ok(userDto);
}

@Valid는 JSR-303 기반의 유효성 검증을 수행합니다.
검증 실패 시 MethodArgumentNotValidException이 자동 발생합니다.

📦 4. 글로벌 예외 처리 – @ControllerAdvice 사용

실무에서는 예외마다 다르게 try-catch를 두는 것보다, 전역 예외 처리 클래스를 설계하는 것이 좋습니다.

@RestControllerAdvice
public class GlobalExceptionHandler {

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

    @ExceptionHandler(Exception.class)
    public ResponseEntity<String> handleAll(Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("서버 오류가 발생했습니다.");
    }
}

🧠 실무 적용 전략

모든 DTO에 반드시 @Valid 애노테이션 적용
검증 메시지는 비즈니스 친화적인 한글 메시지로 커스터마이징
공통 응답 포맷을 맞추기 위해 ApiErrorResponse 클래스를 만들어 관리
필요 시 사용자 정의 예외(BusinessException)를 만들어 도메인 단위로 분리

✅ 마무리 요약

항목 설명

검증 대상	@RequestBody, @ModelAttribute 기반 DTO
검증 도구	@Valid, @Validated, BindingResult
응답 처리	@RestControllerAdvice로 전역 처리
공통 전략	예외 코드, 메시지 표준화 및 공통 응답 구조 적용
추가 도구	Hibernate Validator, 커스텀 애노테이션 정의 가능

📌 다음 편 예고

Spring Boot 시리즈 5편: API 응답 구조 표준화 – 성공/실패 응답 통일 설계 패턴

728x90