[Spring Boot] Custom Validation annotation

Intro

• 사용자 혹은 프론트엔드에서 요청한 데이터를 검증하는 것은 중요
• Spring Boot와 같은 프레임워크에서는 @Valid, @Validated, validation 관련 애너테이션을 사용해서 유효성 검증이 가능함
• 복잡한 비즈니스 로직이나 특정 요구사항에서는 기본적으로 제공하는 검증 애너테이션을 사용하기 어려울 수 있음
• Spring Boot에서는 사용자 정의의 validation을 생성할 수 있음

예제코드

@Getter
@ToString
@JsonNaming(value = PropertyNamingStrategies.SnakeCaseStrategy.class)
public class RegistUserRequest {
    @Pattern(regexp = "^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+.[A-Za-z]{2,6}$", message = "유효한 이메일 형식이 아닙니다.")
    private String email;

    @Pattern(regexp = "^01([0|1|6|7|8|9])-?([0-9]{3,4})-?([0-9]{4})$", message = "유효한 휴대폰 번호가 아닙니다.")
    private String phoneNumber;

    @Min(value = 19, message = "19세 이상 가입 가능합니다.")
    private int age;

    @NotBlank
    private String name;

    @Pattern(regexp = "^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+.[A-Za-z]{2,6}$", message = "유효한 이메일 형식이 아닙니다.")
    private String recommendedEmail;
}

• 위와 같은 요청 데이터를 필요로 할 때 만약 recommendedEmail이 선택 가능한 옵션 값이라고 하자

{
    "email" : "test@naver.com",
    "phone_number" : "010-2034-1122",
    "age" : 19,
    "name" : "test",
    "recommended_email" : ""
}

 

• 요청 데이터에 recommended_email을 보내지 않는다면 validation 애너테이션은 데이터의 유효성 검증을 하지 않지만, 필드와 값을 보내는 경우 유효성 검증을 실시한다

{
    "code": 40001,
    "msg": "데이터 검증에 실패했습니다.",
    "field_errors": [
        {
            "field": "recommendedEmail",
            "rejectedValue": "",
            "reason": "유효한 이메일 형식이 아닙니다."
        }
    ]
}

• validation에 실패한 결과를 받음
• 옵션인 경우 값이 있을 때(값이 없는건 null, "", " "로 정의)만 검증하고 싶을때 기존 validation을 사용할 수 없음
• 또한 email, recommendedEmail과 같이 이메일은 다른 요청에도 반복적으로 사용될 수 있는데 이때 이메일 길이 제한에 대한 요구사항이 변경되는 경우 일일이 모든 필드를 확인하며 정규식을 수정해 줘야함
• 기존 validation의 문제를 해결하기 위해 custom validation annotation을 만들어 사용할 수 있다

(validation 수행 후 발생하는 exception을 공통 response로 정의하는 방법은 이전 글 참고 : 2024.11.09 - [BE/🍃 Spring] - [Spring Boot] RestControllerAdvice로 Validation Exception 핸들링하기)

 

기대효과

• 가독성 향상
• 중복되는 코드 최소화
• 기존 validtion에서 구현하기 힘든 기능 구현

 

Custom annotation

@Constraint(validatedBy = RestrictionValidator.class)
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface Restriction {
    boolean required() default false;
    int min() default Integer.MIN_VALUE;
    int max() default Integer.MAX_VALUE;
    PatternType patternType() default PatternType.NONE;
    String message() default "유효하지 않은 값입니다.";

    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};

    enum PatternType {
        NONE,
        PHONE,
        EMAIL
    }
}

 

• 애너테이션에서 사용할 옵션 required, min, max, patternType, message를 추가
• 자주 사용되는 패턴은 PatternType으로 정의

ConstraintValidator

public class RestrictionValidator implements ConstraintValidator<Restriction, Object> {

    private boolean required;
    private int min;
    private int max;
    private Restriction.PatternType patternType;
    
    private static final Pattern PHONE_PATTERN = Pattern.compile("^01([0|1|6|7|8|9])-?([0-9]{3,4})-?([0-9]{4})$");
    private static final Pattern EMAIL_PATTERN = Pattern.compile("^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+.[A-Za-z]{2,6}$");

    @Override
    public void initialize(Restriction constraintAnnotation) {
        this.required = constraintAnnotation.required();
        this.min = constraintAnnotation.min();
        this.max = constraintAnnotation.max();
        this.patternType = constraintAnnotation.patternType();
    }

    @Override
    public boolean isValid(Object value, ConstraintValidatorContext context) {
        if (required && value == null) {
            return false;
        }

        if (value instanceof String stringValue) {
            if (required && stringValue.trim().isEmpty()) {
                return false;
            }

            if (!required && stringValue.trim().isEmpty()) {
                return true;
            }

            if (stringValue.length() < min || stringValue.length() > max) {
                return false;
            }

            if (patternType == Restriction.PatternType.PHONE && !PHONE_PATTERN.matcher(stringValue).matches()) {
                return false;
            }

            if (patternType == Restriction.PatternType.EMAIL && !EMAIL_PATTERN.matcher(stringValue).matches()) {
                return false;
            }

        } else if (value instanceof Integer intValue) {
            if (intValue < min || intValue > max) {
                return false;
            }
        }

        return true;
    }
}

 

• isValid에서 false를 반환하면 MethodArgumentNotValidException이 발생함
• ConstraintValidator<Restirction, Object>는 각각 custom annotation, 검증할 객체의 타입
• 검증할 객체는 int, String 등 다양하므로 Object로 지정

적용

@Getter
@ToString
@JsonNaming(value = PropertyNamingStrategies.SnakeCaseStrategy.class)
public class RegistUserRequest {
    @Restriction(required = true, patternType = Restriction.PatternType.EMAIL, message = "유효한 이메일 형식이 아닙니다.")
    private String email;

    @Restriction(required = true, patternType = Restriction.PatternType.PHONE, message = "유효한 휴대폰 번호 형식이 아닙니다.")
    private String phoneNumber;

    @Restriction(required = true, min = 19, message = "19세 이상 부터 가입 가능합니다.")
    private int age;

    @Restriction(required = true, message = "이름은 필수 값입니다.")
    private String name;

    @Restriction(required = false, patternType = Restriction.PatternType.EMAIL, message = "유효한 이메일 형식이 아닙니다.")
    private String recommendedEmail;
}

 

• 기존 Validation 로직들을 제거하고 Restriction 추가

 

테스트

{
    "email" : "test@naver.com",
    "phone_number" : "010-2034-1122",
    "age" : 12,
    "name" : "test",
    "recommended_email" : ""
}

 

//    @Restriction(required = true, min = 19, message = "19세 이상 부터 가입 가능합니다.")
//    private int age;

{
    "code": 40001,
    "msg": "데이터 검증에 실패했습니다.",
    "field_errors": [
        {
            "field": "age",
            "rejectedValue": "12",
            "reason": "19세 이상 부터 가입 가능합니다."
        }
    ]
}

 

• request에서 유효하지 않은 age를 보내면, 검증에 실패했다는 결과를 얻을 수 있음

---

    @Restriction(required = false, patternType = Restriction.PatternType.EMAIL, message = "유효한 이메일 형식이 아닙니다.")
    private String recommendedEmail;

• recommended_email의 경우 옵션 값이기 때문에 값이 있는 경우에만 이메일 패턴 검증

// 테스트 1
{
    "email" : "test@naver.com",
    "phone_number" : "010-2034-1122",
    "age" : 19,
    "name" : "test",
    "recommended_email" : ""
}

// 테스트 2
{
    "email" : "test@naver.com",
    "phone_number" : "010-2034-1122",
    "age" : 19,
    "name" : "test",
    "recommended_email" : "test"
}

 

• 위와 같이 request를 보낸 경우

// test1
RegistUserRequest(email=test@naver.com, phoneNumber=010-2034-1122, age=19, name=test, recommendedEmail=)

// test2
{
    "code": 40001,
    "msg": "데이터 검증에 실패했습니다.",
    "field_errors": [
        {
            "field": "recommendedEmail",
            "rejectedValue": "test",
            "reason": "유효한 이메일 형식이 아닙니다."
        }
    ]
}

 

• test1에서는 recommendedEmail의 값이 없어 검증을 하지 않았고, 의도한 response값을 리턴
• test2에서는 recommendedEmail의 값이 있으므로 이메일 패턴을 검증하고 에러 메세지를 request를 요청한 프론트에게 전달