SpringBoot自定义实体类字段的校验注解

在Spring Boot项目中，我们经常需要对请求参数进行格式或业务规则的校验。虽然Spring Boot提供了如@NotNull、@Size等基础校验注解，但在实际开发中往往无法满足复杂的业务需求。但是在Controller层写大量的 if 语句的判断逻辑又实在不优雅，好在 Spring Validator 为我们提供了一种自定义校验注解的方法实现优雅的参数校验。

简而言之，自定义校验注解的优点大概有以下几点：

• 统一性：避免在Controller层写大量if判断逻辑
• 可复用性：可以在多个字段或多个实体类中重复使用
• 可维护性：校验逻辑和业务逻辑分离，便于后期修改和扩展

自定义校验注解的实现步骤：

一、 创建自定义注解类

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = ValidN1Validator.class)
public @interface ValidN1 {
    String message() default "必须1位数字";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

解析：

1. @Target({ElementType.FIELD, ElementType.PARAMETER})：表示该注解可以用于字段或方法参数上。例如，你可以标注在实体类字段上，也可以用在Controller方法的参数上。

2. @Retention(RetentionPolicy.RUNTIME)：表示该注解在运行时依然可用，这样Spring才能在运行时读取并执行校验逻辑。

3. @Constraint(validatedBy = ValidN1Validator.class)：指定该注解由哪个校验器来处理，这里是 ValidN1Validator 类。

4. message()：校验失败时返回的默认错误提示信息。

5. groups()：分组校验使用，允许你根据不同的业务场景选择性地启用某些校验规则。

6. payload()：可选属性，通常用于携带额外元数据，如严重级别等。

二、实现对应的校验器类

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;

public class ValidN1Validator implements ConstraintValidator<ValidN1, Integer> {
    @Override
    public boolean isValid(Integer value, ConstraintValidatorContext context) {
        if(value == null){
            return true;
        }
        if(value >= 0 && value <= 9){
            return true;
        }else {
            return false;
        }
    }
}

解析：

1. 接口实现：ConstraintValidator<ValidN1, Integer>

• 第一个泛型参数是注解类型；
• 第二个泛型参数是要校验的数据类型，这里是Integer。

2. 方法实现：isValid(Integer value, ConstraintValidatorContext context)

• 核心校验逻辑，判断传入的值是否符合要求。

三、在实体类中添加注解

public class User {
    private String name;

    @ValidN1
    private Integer sex;
}

四、统一返回错误信息（可选）

为了统一返回错误信息，我们可以使用 @RestControllerAdvice 来捕获校验异常。

@RestControllerAdvice
@Slf4j
public class ValidationExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<RequestDto> handleValidationExceptions(MethodArgumentNotValidException ex) {
        BindingResult result = ex.getBindingResult();
        List<String> errors = result.getAllErrors().stream()
                .map(ObjectError::getDefaultMessage)
                .collect(Collectors.toList());

        RequestDto dto = new RequestDto();
        dto.setCode(-1);
        dto.setMessage("参数校验失败：" + errors);

        return ResponseEntity.badRequest().body(dto);
    }
}

这样当用户传入非法参数时，系统会返回类似如下格式的响应：

{
  "code": -1,
  "message": "参数校验失败：[时间戳格式错误]"
}