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/

约束(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({
   
   <