Java Bean Validation规范

Java中的数据校验

​ JSR：全称Java Specification Requests，意思是Java 规范提案。我们可以将其理解为Java为一些功能指定的一系列统一的规范。跟数据校验相关的最新的JSR为JSR 380。

​ Bean Validation 2.0 是JSR第380号标准。该标准连接如下：https://www.jcp.org/en/egc/view?id=380
​ Bean Validation的主页：http://beanvalidation.org
​ Bean Validation的参考实现：https://github.com/hibernate/hibernate-validator

Bean Validation 2.0的唯一实现就是Hibernate Validator，对应版本为6.0.1.Final(JDK8)

Bean Validation 3.0的唯一实现就是Hibernate Validator，对应版本为7.0.5.Final(JDK 9) ，8.0.0.Final(JDK10)

内置的校验注解

​ 参考：https://download.oracle.com/otndocs/jcp/bean_validation-2_0_0-final-spec/

验证注解	验证的数据类型	说明
@AssertFalse	Boolean,boolean	验证注解的元素值是false
@AssertTrue	Boolean,boolean	验证注解的元素值是true
@NotNull	任意类型	验证注解的元素值不是null
@Null	任意类型	验证注解的元素值是null
@Min(value=值)	BigDecimal，BigInteger, byte,short, int, long，等任何Number或CharSequence（存储的是数字）子类型	验证注解的元素值大于等于@Min指定的value值
@Max（value=值）	和@Min要求一样	验证注解的元素值小于等于@Max指定的value值
@DecimalMin(value=值)	和@Min要求一样	验证注解的元素值大于等于@ DecimalMin指定的value值
@DecimalMax(value=值)	和@Min要求一样	验证注解的元素值小于等于@ DecimalMax指定的value值
@Digits(integer=整数位数, fraction=小数位数)	和@Min要求一样	验证注解的元素值的整数位数和小数位数上限
@Size(min=下限, max=上限)	字符串、Collection、Map、数组等	验证注解的元素值的在min和max（包含）指定区间之内，如字符长度、集合大小
@Past	java.util.Date,java.util.Calendar;Joda Time类库的日期类型	验证注解的元素值（日期类型）比当前时间早
@Future	与@Past要求一样	验证注解的元素值（日期类型）比当前时间晚
@NotBlank	CharSequence子类型	验证注解的元素值不为空（不为null、去除首位空格后长度为0），不同于@NotEmpty，@NotBlank只应用于字符串且在比较时会去除字符串的首位空格
@Length(min=下限, max=上限)	CharSequence子类型	验证注解的元素值长度在min和max区间内
@NotEmpty	CharSequence子类型、Collection、Map、数组	验证注解的元素值不为null且不为空（字符串长度不为0、集合大小不为0）
@Range(min=最小值, max=最大值)	BigDecimal,BigInteger,CharSequence, byte, short, int, long等原子类型和包装类型	验证注解的元素值在最小值和最大值之间
@Email(regexp=正则表达式,flag=标志的模式)	CharSequence子类型（如String）	验证注解的元素值是Email，也可以通过regexp和flag指定自定义的email格式
@Pattern(regexp=正则表达式,flag=标志的模式)	String，任何CharSequence的子类型	验证注解的元素值与指定的正则表达式匹配
@Valid	任何非原子类型	指定递归验证关联的对象如用户对象中有个地址对象属性，如果想在验证用户对象时一起验证地址对象的话，在地址对象上加@Valid注解即可级联验证
@FutureOrPresent
@Negative
@NegativeOrZero
@PastOrPresent
@Positive
@PositiveOrZero

约束(Constraint)定义

约束是一系列约束注解与约束校验实现的组合。约束注解可以应用在types, fields, methods,constructors, parameters, container elements 或其他约束注解。

Bean校验API的默认包名为javax.validation。

约束注解

约束通过在Java Bean上应用约束注解来表达。约束注解是应用了javax.validation.Constraint，并且retention策略设置为RUNTIME的注解。

Documented
@Target({
    ANNOTATION_TYPE })
@Retention(RUNTIME)
public @interface Constraint {
   
	Class<? extends ConstraintValidator<?, ?>>[] validatedBy();
}

Generic 约束注解可以应用于：

• FIELD for constrained attributes
• METHOD for constrained getters and constrained method return values
• CONSTRUCTOR for constrained constructor return values
• PARAMETER for constrained method and constructor parameters
• TYPE for constrained beans
• ANNOTATION_TYPE for constraints composing other constraints
• TYPE_USE for container element constraints

Cross-parameter约束注解可以应用于：

• METHOD
• CONSTRUCTOR
• ANNOTATION_TYPE for cross-parameter constraints composing other cross-parameter constraints

一个Constraint注解可以同时应用于Generic 约束注解 和 Cross-parameter约束注解

Constraint 定义属性

在指定一个注解应用于Java Bean的同时，需要指定属性，这些属性映射为注解元素。注解元素包括：message, groups, validationAppliesTo 和payload ，为保留名称，注解元素命名不能以valid 开头，constraint 可以使用其他元素名称作为其属性。

message

每个约束注解都必须定义一个String类型的message 元素。

String message() default "{com.acme.constraint.MyConstraint.message}";

message元素的值用于描述错误信息。

groups

groups用于定义约束定义关联到哪个处理Group，类型为Class<?>[]

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

默认值为空数组。如果未定义，则表示使用Default 组。

payload

类型为 Payload[]，默认值为空数组。

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

public interface Payload {
   
}

payload通常用于定义关联到约束注解的元数据，在client进行校验时使用。

validationAppliesTo

ConstraintTarget 枚举类型，用于指定注解应用于什么类型。

ConstraintTarget validationAppliesTo() default ConstraintTarget.IMPLICIT;
public enum ConstraintTarget {
   
  /**
    当没有方法和构造函数时，表示type，field。当方法和构造函数没有参数时，表示返回值，当没有返回值时，表示参数。
  */
  IMPLICIT,

  RETURN_VALUE,
  PARAMETERS
}

示例：@Min

@Target({
    METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
@Retention(RUNTIME)
@Repeatable(List.class)
@Documented
@Constraint(validatedBy = {
    })
public @interface Min {
   

	String message() default "{javax.validation.constraints.Min.message}";

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

	Class<? extends Payload>[] payload() default {
    };
	long value();
    
	@Target({
    METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
	@Retention(RUNTIME)
	@Documented
	@interface List {
   

		Min[] value();
	}
}

多值约束

多个同一约束(有不同的属性)应用于同一个target。为了支持这个特性， Bean Validation提供者对value属性返回 约束注解 数组的注解进行了特殊处理。value属性值的每个元素都应用于目标。

借助于JDK8 的@Repeatable注解，在每个约束注解类定义一个 List注解，用于此类约束注解的容器。(见 @Min 的定义代码)

示例：

//定义约束注解
@Documented
@Constraint(validatedBy = ZipCodeValidator.class)
@Target({
    METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
@Retention(RUNTIME)
@Repeatable(List.class)
public @interface ZipCode {
   
  String countryCode();
  String message() default "{com.acme.constraint.ZipCode.message}";
  Class<?>[] groups() default {
   };
  Class<? extends Payload>[] payload() default {
   };
  /**
  * 此处定义了 ZipCode 的容器
  */
  @Target({
    METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
  @Retention(RUNTIME)
  @Documented
  @interface List {
   
  ZipCode[] value();
  }
}

//使用注解：  方式1.
public class Address {
   
  @ZipCode(countryCode = "fr", groups = Default.class, message = "zip code is not valid")
  @ZipCode(
  countryCode = "fr",
  groups = SuperUser.class,
  message = "zip code invalid. Requires overriding before saving."
  )
  private String zipCode;
}
//使用注解：方式2，使用List。
public class Address {
   
  @ZipCode.List( {
   
  @ZipCode(countryCode="fr", groups=Default.class,
  message = "zip code is not valid"),
  @ZipCode(countryCode="fr", groups=SuperUser.class,
  message = "zip code invalid. Requires overriding before saving.")
  } )
  private String zipCode;
}

约束组合

组合多个不同类型的约束。定义一个注解，把要应用的多个注解 应用于 此注解的定义上。

示例：

@Pattern(regexp = "[0-9]*")    // 约束1
@Size(min = 5, max = 5)        // 约束2
@Constraint(validatedBy = FrenchZipCodeValidator.class)  //注意此处
@ReportAsSingleViolation  //所有约束都产生在一个错误报告中
@Documented
@Target({
    METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
@Retention(RUNTIME)
public @interface FrenchZipCode {
   
  String message() default "Wrong zip code";
  Class<?>[] groups() default {
   };
  Class<? extends Payload>[] payload() default {
   };
  @Target({
    METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
  @Retention(RUNTIME)
  @Documented
  @interface List {
   
  FrenchZipCode[] value();
  }
}

默认情况下，每个约束都会产生一个错误报告，每个composing约束的groups 、payload、validationAppliesTo属性 会继承主约束(上例：FrenchZipCode)的对应属性，自己的定义会忽略。

如果需要所有约束的错误都产生在一个错误报告中，则使用注解@ReportAsSingleViolation。当发现第一个错误时即停止后续校验。

@Target({
    ANNOTATION_TYPE })
@Retention(RUNTIME)
@Documented
public @interface ReportAsSingleViolation {
   
}

使用 @OverridesAttribute

使用 @OverridesAttribute，可以在主约束中通过属性覆盖 组合约束的属性。

@Documented
@Retention(RUNTIME)
@Target({
    METHOD })