Spring REST 接口校验Validation

历史和概念

<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.0.14.Final</version>
    <scope>compile</scope>
</dependency>

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

@Valid和@Validated的区别

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Validated

@Target({ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Valid 

如何实现校验

约束注解的类型

• 通过向方法或构造函数的参数添加约束注解来指定方法或构造函数的前置条件

• 通过在方法体上添加约束注解来给方法或构造函数指定后置条件

写代码校验

//更多使用方式看Validation的注解
//线程安全
Validator validator = Validation.buildDefaultValidatorFactory().getValidator();
validator.validate(Object obj, Class<?>[] groups);

集成Spring

• 先说第一个问题：为什么有的时候，不需要类上@Validated注解就能生效
那什么时候不需要@Validated就能生效呢？对于controller，当在@RequestBody上应用@Valid的时候，是不需要额外的处理的，因为Spring在处理post body的数据绑定时，借助于RequestResponseBodyMethodProcessor，完成了数据的校验。
注意，以下的情况，其request body不是一个完整的对象，所以spring不会进行校验

@PostMapping("test5")
public ResponseEntity<?> test5(@Valid @RequestBody List<Person> personList) {
    return ResponseEntity.ok("ok");
}

@PostMapping("test6")
public ResponseEntity<?> test6(@Validated @RequestBody List<Person> personList) {
    return ResponseEntity.ok("ok");
}
@PostMapping("test7")
public ResponseEntity<?> test7(@Valid @NotEmpty @RequestBody List<Person> personList) {
    return ResponseEntity.ok("ok");
}

• @Validated和@Valid能互相替代么
在二者都能使用的场景，是完全可以互相替代的，其作用都是声明了当前属性、对象or参数需要进行校验
不能互相代替的场景：用在属性上；用在类上；分组校验

注解的嵌套

@Data
public class Person {

    // 错误消息message是可以自定义的
    @NotNull(groups = Simple.class)
    public String name;

    @Positive(groups = Default.class)
    public Integer age;

    @NotNull(groups = Complex.class)
    @NotEmpty(groups = Complex.class)
    private List<@Email String> emails;

    @Valid
    private NestPerson nestPerson;

    // 定义两个组 Simple组和Complex组
    public interface Simple {
    }

    public interface Complex {

    }
}

// 用于进行嵌套校验
@Data
public class NestPerson {
    @NotNull
    String name;

    @Valid
    Person person;
}

注解的继承

• 方法调用方要满足前置条件不能在子类型中得到加强

• 方法调用方要保证后置条件不能在子类型中被削弱

最佳实践

• controller固定添加@Validated

• query方法如果是query object，参数上加@Valid
@Validated生成的AOP会验证Object本身，但是Object内属性属于嵌套，不会验证，必须添加@Valid才行

• post方法body参数添加@Valid

• 需要分组验证，使用@Validated替代@Valid（并不需要放在方法上）

• object内嵌套了object，被嵌套的属性加@Valid

• request param和path variable直接使用具体的验证注解

常用验证注解

JSR标准

1. @Size(min=, max=)
检查元素个数是否在 min（含）和 max（含）之间 支持数据类型：CharSequence，Collection，Map, arrays。不支持数字！！；null视为通过

2. @NotEmpty
检查元素是否不为 null 或 空 支持数据类型：CharSequence, Collection, Map, arrays；null视为不通过

3. @NotBlank
不为null，且至少包含一个非空格字符。与 @NotEmpty 的不同之处在于，此约束只能应用于字符序列，并且忽略尾随空格。 支持数据类型：CharSequence

4. @Max(value=)
检查值是否小于或等于指定的最大值 支持的数据类型： BigDecimal, BigInteger, byte, short, int, long, 原生类型的封装类, CharSequence 的任意子类（字符序列表示的数字，即可以转换为字数字的字符串）, Number 的任意子类, javax.money.MonetaryAmount 的任意子类

5. @Min(value=)
检查值是否大于或等于指定的最大值 支持的数据类型： 同@Max

6. @AssertFalse
检查元素是否为 false，支持数据类型：boolean、Boolean

7. @AssertTrue
检查元素是否为 true，支持数据类型：boolean、Boolean

8. @DecimalMax(value=, inclusive=)
inclusive：boolean，默认 true，表示是否包含，是否等于 value：当 inclusive=false 时，检查带注解的值是否小于指定的最大值。当 inclusive=true 检查该值是否小于或等于指定的最大值。参数值是根据 bigdecimal 字符串表示的最大值。 支持数据类型：BigDecimal、BigInteger、CharSequence、（byte、short、int、long 和其封装类）

9. @DecimalMin(value=, inclusive=)
支持数据类型：BigDecimal、BigInteger、CharSequence、（byte、short、int、long 和其封装类） inclusive：boolean，默认 true，表示是否包含，是否等于 value： 当 inclusive=false 时，检查带注解的值是否大于指定的最大值。当 inclusive=true 检查该值是否大于或等于指定的最大值。参数值是根据 bigdecimal 字符串表示的最小值。

10. @Digits(integer=, fraction=)
检查值是否为最多包含 integer 位整数和 fraction 位小数的数字 支持的数据类型： BigDecimal, BigInteger, CharSequence, byte, short, int, long 、原生类型的封装类、任何 Number 子类。

11. @Email
检查指定的字符序列是否为有效的电子邮件地址。可选参数 regexp 和 flags 允许指定电子邮件必须匹配的附加正则表达式（包括正则表达式标志）。 支持的数据类型：CharSequence

12. @NotNull
检查值是否不为 null 支持数据类型：任何类型

13. @Negative
检查元素是否严格为负数。零值被认为无效。 支持数据类型： BigDecimal, BigInteger, byte, short, int, long, 原生类型的封装类, CharSequence 的任意子类（字符序列表示的数字）, Number 的任意子类, javax.money.MonetaryAmount 的任意子类

14. @NegativeOrZero
检查元素是否为负或零。 支持数据类型： BigDecimal, BigInteger, byte, short, int, long, 原生类型的封装类, CharSequence 的任意子类（字符序列表示的数字）, Number 的任意子类, javax.money.MonetaryAmount 的任意子类

15. @Positive
检查元素是否严格为正。零值被视为无效。 支持数据类型： BigDecimal, BigInteger, byte, short, int, long, 原生类型的封装类, CharSequence 的任意子类（字符序列表示的数字）, Number 的任意子类, javax.money.MonetaryAmount 的任意子类

16. @PositiveOrZero
检查元素是否为正或零。 支持数据类型： BigDecimal, BigInteger, byte, short, int, long, 原生类型的封装类, CharSequence 的任意子类（字符序列表示的数字）, Number 的任意子类, javax.money.MonetaryAmount 的任意子类

17. @Null
检查值是否为 null 支持数据类型：任何类型

18. @Future
检查日期是否在未来 支持的数据类型： java.util.Date, java.util.Calendar, java.time.Instant, java.time.LocalDate, java.time.LocalDateTime, java.time.LocalTime, java.time.MonthDay, java.time.OffsetDateTime, java.time.OffsetTime, java.time.Year, java.time.YearMonth, java.time.ZonedDateTime, java.time.chrono.HijrahDate, java.time.chrono.JapaneseDate, java.time.chrono.MinguoDate, java.time.chrono.ThaiBuddhistDate 如果 Joda Time API 在类路径中，ReadablePartial 和ReadableInstant 的任何实现类

19. @FutureOrPresent
检查日期是现在或将来 支持数据类型：同@Future

20. @Past
检查日期是否在过去 支持数据类型：同@Future

21. @PastOrPresent
检查日期是否在过去或现在 支持数据类型：同@Future

22. @Pattern(regex=, flags=)
根据给定的 flag 匹配，检查字符串是否与正则表达式 regex 匹配 支持数据类型：CharSequence

hibernate提供的注解

1. @Range：把@Max和@Min组合起来了

2. @Length：

3. @DurationMax

4. @DurationMin

5. @CodePointLength

6. @UniqueElements

7. @URL

创建自定义约束

• 创建一个约束注解

• 实现一个验证器

• 定义一个默认的错误消息

创建约束注解

@Target({ FIELD, METHOD, PARAMETER, ANNOTATION_TYPE, TYPE_USE })
@Retention(RUNTIME)
@Constraint(validatedBy = CheckCaseValidator.class)
@Documented@Repeatable(List.class)
public @interface CheckCase {
    String message() default "{org.jys.CheckCase}";
    Class<?>[] groups() default { };
    Class<? extends Payload>[] payload() default { };
    CaseMode value();

    @Target({ FIELD, METHOD, PARAMETER, ANNOTATION_TYPE })
    @Retention(RUNTIME)
    @Documented
    @interface List {
        CheckCase[] value();
    }
}

实现验证器

public class CheckCaseValidator implements ConstraintValidator<CheckCase, String> {
    private CaseMode caseMode;
    @Override
    public void initialize(CheckCase constraintAnnotation) {
        this.caseMode = constraintAnnotation.value();
    }
    @Override
    public boolean isValid(String object, ConstraintValidatorContext constraintContext) {
        if ( object == null ) {
            return true;
        }
        if ( caseMode == CaseMode.UPPER ) {
            return object.equals( object.toUpperCase() );
        }else {
            return object.equals( object.toLowerCase() );
        }
    }
}

定义默认错误消息

org.jys.CheckCase = 核载人数为{value}，请勿超载

分组

public class SuperCar extends Car {
    @AssertTrue(
            message = "Race car must have a safety belt",
            groups = RaceCarChecks.class
    )
    private boolean safetyBelt;
    // getters and setters ...
}
public interface RaceCarChecks extends Default {}

分组序列

@GroupSequence({ Default.class, CarChecks.class, DriverChecks.class })
public interface OrderedChecks {}

重新定义默认分组序列

@GroupSequence({ RentalChecks.class, CarChecks.class, RentalCar.class })
public class RentalCar extends Car {}

1. 实现接口：DefaultGroupSequenceProvider

2. 在指定类上使用 @GroupSequenceProvider，并指定 value 为上一步的类

public class RentalCarGroupSequenceProvider
        implements DefaultGroupSequenceProvider<RentalCar> {
    @Override
    public List<Class<?>> getValidationGroups(RentalCar car) {
        List<Class<?>> defaultGroupSequence = new ArrayList<Class<?>>();
        defaultGroupSequence.add( RentalCar.class );
        if ( car != null && !car.isRented() ) {
            defaultGroupSequence.add( CarChecks.class );
        }
        return defaultGroupSequence;
    }
}

@GroupSequenceProvider(RentalCarGroupSequenceProvider.class)
public class RentalCar extends Car {
    @AssertFalse(message = "The car is currently rented out", groups = RentalChecks.class)
    private boolean rented;
    public RentalCar(String manufacturer, String licencePlate, int seatCount) {
        super( manufacturer, licencePlate, seatCount );
    }
    public boolean isRented() {
        return rented;
    }
    public void setRented(boolean rented) {
        this.rented = rented;
    }
}

分组转换

// 当 driver 为 null 时，不会级联验证，使用的是默认分组，当级联验证时，使用的是 DriverChecks 分组
@Valid
@ConvertGroup(from = Default.class, to = DriverChecks.class)
private Driver driver;

参考文章

1. Complete Guide to Validation With Spring Boot

2. validator 自动化校验

3. Spring官网阅读（十七）Spring中的数据校验

4. Jakarta Bean Validation specification