[TIL] 2025-01-31_@Valid

🔫 일정관리 API 를 구현하며 겪은 문제점과 해결방법, 새로 알게된 점을 기록합니다.

📋 기획 정의

null 체크 및 특정 패턴에 대한 검증 수행

• 설명
  • 유효성 검사
    1. 잘못된 입력이나 요청을 미리 방지할 수 있습니다.
    2. 데이터의 무결성을 보장하고 애플리케이션의 예측 가능성을 높여줍니다.
    3. Spring에서 제공하는 @Valid 어노테이션을 이용할 수 있습니다.
• 조건
  • 할일은 최대 200자 이내로 제한, 필수값 처리
  • 비밀번호는 필수값 처리
  • 담당자의 이메일 정보가 형식에 맞는지 확인

@Valid

객체의 유효성 검사를 수행하는 데 사용되는 어노테이션
사용자가 입력한 데이터가 유효한 지 확인할 수 있다.

☑️ Hibernate Validator 공식문서
📋 버전별 공식 매뉴얼

주요기능

• 유효성 검사: @Valid 어노테이션이 붙은 객체나 그 속성에 대해 유효성 검사 규칙을 적용한다. 객체에 정의된 제약조건 (@NotNull, @Size, @Min, @Max 등)을 기반으로 검사한다.
• 자동 검사: Spring에서는 @Valid가 붙은 객체가 메서드 파라미터로 들어오면, 해당 객체가 자동으로 유효성 검사를 받는다. 주로 컨트롤러에서 HTTP 요청 파라미터를 바인딩할 때 유용하게 사용된다.

의존성 주입

build.gradle의 dependencies에 implementation 'org.springframework.boot:spring-boot-starter-validation' 추가

사용예시

1. DTO 클래스에서 제약 조건 설정

@Getter
public class ScheduleRequestDto {

    private Long authorId;
    private String author;
    @NotNull(message = "할일은 필수값입니다.")
    @Size(max = 200, message = "할일은 최대 200자 이하로 입력해 주세요.")
    private String todo;
    @NotNull(message = "비밀번호는 필수값입니다.")
    private String password;
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    private Date modDate;

}

• @Size: 문자열, 배열, 리스트 등에서 길이(크기) 조건 명시
  • 길이가 지정된 범위를 벗어나면 유효성 검사에서 오류 발생
  • 문자열의 길이를 제한하고 싶을 때 유용한 어노테이션
    • min: 허용되는 최소 크기. 기본값은 0
    • max: 허용되는 최대 크기. 기본값은 Integer.MAX_VALUE
    • message: 검증 실패 시 반환될 오류 메세지 설정
  • Spring 에서는 @Valid나 @Validated 와 함께 사용해야 유효성 검사를 자동으로 처리할 수 있다.

• @NotNull: 해당 필드가 null 이 아니어야 한다는 조건 명시
  빈 문자열이나 0, false 등은 허용되지만, null 은 허용되지 않는다.

@NotNull 과 @NotEmpty, @NotBlank의 차이점

• @NotNull: 필드가 null이 아닌지 검증. 빈 문자열("")은 허용.
• @NotEmpty: 필드가 null이 아니고, 비어 있지 않아야 한다는 제약 조건. @NotEmpty는 문자열이나 컬렉션에 적용되며, 빈 문자열, 빈 리스트 등도 허용하지 않는다.
• @NotBlank: 문자열 필드에 적용되며, null이 아니고, 공백 문자열도 허용하지 않는다. 즉, " "와 같은 공백만 있는 문자열은 유효하지 않다고 판단한다.

2. 컨트롤러에서 @Valid 사용

@PostMapping
public ResponseEntity<ScheduleResponseDto> saveSchedule(@RequestBody @Valid ScheduleRequestDto dto) {
        return new ResponseEntity<>(scheduleService.saveSchedule(dto), HttpStatus.OK);
    }

동작원리

• @Valid 어노테이션이 붙은 객체는 해당 객체의 필드에 설정된 유효성 제약 조건을 기준으로 검사가 수행된다.
• 검사 결과가 실패하면, MethodArgumentNotValidException 예외가 발생하고, Spring은 이 예외를 자동으로 처리하여 400 (Bad Request) 응답을 반환한다.

@ExceptionHandler 적용

e.getMessage() 를 detail 에 넘기면 복잡한 에러 로그가 출력된다. 사용자 입장에서 에러 로그를 해석하기 어렵다.

• e.getMessage() 오버라이딩하여 예외메세지를 출력한다
  : 클라이언트에서는 어떤 필드에 적용된 제약조건 검사가 실패했는지만 알면 된다.

• 필드 제약조건 어노테이션에 작성한 메세지 출력하기
  ▶︎ GlobalExceptionHandler.java

	@ExceptionHandler(MethodArgumentNotValidException.class)
    private ResponseEntity<ErrorResponseDto> handleMethodArgumentNotValidException(MethodArgumentNotValidException e) {
        StringBuilder errorMsg = new StringBuilder();
        for (ObjectError error : e.getBindingResult().getAllErrors()) {
            errorMsg.append(error.getDefaultMessage()).append(" ");
        }
        return ErrorResponseDto.errResponseEntity(new CustomException(ErrorCode.INVALID_CONSTRAINTS, errorMsg.toString()));
    }

• e.getBindingResult().getAllErrors(): BindingResult에서 오류가 있을 경우, getAllErrors()를 호출하여 모든 오류 정보를 가져올 수 있다.
• 각 오류 객체는 defaultMessage 속성을 통해 오류 메시지를 반환하므로 이를 사용자에게 적절히 표시하거나 로깅할 수 있다.