原來工作幾年了，只用了資料校驗的皮毛~

前言

不知不覺Spring Boot專欄文章已經寫到第十四章了，無論寫的好與不好，作者都在盡力寫的詳細，寫的與其它的文章不同，每一章都不是淺嘗輒止。如果前面的文章沒有看過的朋友，點選這裡前往。

今天介紹一下 Spring Boot 如何優雅的整合JSR-303進行引數校驗，說到引數校驗可能都用過，但是你真的會用嗎？網上的教程很多，大多是簡單的介紹。

什麼是 JSR-303？

JSR-303 是 JAVA EE 6 中的一項子規範，叫做 Bean Validation。

Bean Validation 為 JavaBean 驗證定義了相應的後設資料模型和API。預設的後設資料是Java Annotations，通過使用 XML 可以對原有的後設資料資訊進行覆蓋和擴充套件。在應用程式中，通過使用Bean Validation 或是你自己定義的 constraint，例如 @NotNull, @Max, @ZipCode ， 就可以確保資料模型（JavaBean）的正確性。constraint 可以附加到欄位，getter 方法，類或者介面上面。對於一些特定的需求，使用者可以很容易的開發定製化的 constraint。Bean Validation 是一個執行時的資料驗證框架，在驗證之後驗證的錯誤資訊會被馬上返回。

新增依賴

Spring Boot整合JSR-303只需要新增一個starter即可，如下：

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

內嵌的註解有哪些？

Bean Validation 內嵌的註解很多，基本實際開發中已經夠用了，註解如下：

註解	詳細資訊
@Null	被註釋的元素必須為 null
@NotNull	被註釋的元素必須不為 null
@AssertTrue	被註釋的元素必須為 true
@AssertFalse	被註釋的元素必須為 false
@Min(value)	被註釋的元素必須是一個數字，其值必須大於等於指定的最小值
@Max(value)	被註釋的元素必須是一個數字，其值必須小於等於指定的最大值
@DecimalMin(value)	被註釋的元素必須是一個數字，其值必須大於等於指定的最小值
@DecimalMax(value)	被註釋的元素必須是一個數字，其值必須小於等於指定的最大值
@Size(max, min)	被註釋的元素的大小必須在指定的範圍內
@Digits (integer, fraction)	被註釋的元素必須是一個數字，其值必須在可接受的範圍內
@Past	被註釋的元素必須是一個過去的日期
@Future	被註釋的元素必須是一個將來的日期
@Pattern(value)	被註釋的元素必須符合指定的正規表示式

以上是Bean Validation的內嵌的註解，但是Hibernate Validator在原有的基礎上也內嵌了幾個註解，如下。

註解	詳細資訊
@Email	被註釋的元素必須是電子郵箱地址
@Length	被註釋的字串的大小必須在指定的範圍內
@NotEmpty	被註釋的字串的必須非空
@Range	被註釋的元素必須在合適的範圍內

如何使用？

引數校驗分為簡單校驗、巢狀校驗、分組校驗。

簡單校驗

簡單的校驗即是沒有巢狀屬性，直接在需要的元素上標註約束註解即可。如下：

@Data
public class ArticleDTO {

    @NotNull(message = "文章id不能為空")
    @Min(value = 1,message = "文章ID不能為負數")
    private Integer id;

    @NotBlank(message = "文章內容不能為空")
    private String content;

    @NotBlank(message = "作者Id不能為空")
    private String authorId;

    @Future(message = "提交時間不能為過去時間")
    private Date submitTime;
}

同一個屬性可以指定多個約束，比如@NotNull和@MAX,其中的message屬性指定了約束條件不滿足時的提示資訊。

以上約束標記完成之後，要想完成校驗，需要在controller層的介面標註@Valid註解以及宣告一個BindingResult型別的引數來接收校驗的結果。

下面簡單的演示下新增文章的介面，如下：

/**
     * 新增文章
     */
    @PostMapping("/add")
    public String add(@Valid @RequestBody ArticleDTO articleDTO, BindingResult bindingResult) throws JsonProcessingException {
        //如果有錯誤提示資訊
        if (bindingResult.hasErrors()) {
            Map<String , String> map = new HashMap<>();
            bindingResult.getFieldErrors().forEach( (item) -> {
                String message = item.getDefaultMessage();
                String field = item.getField();
                map.put( field , message );
            } );
            //返回提示資訊
            return objectMapper.writeValueAsString(map);
        }
        return "success";
    }

僅僅在屬性上新增了約束註解還不行，還需在介面引數上標註@Valid註解並且宣告一個BindingResult型別的引數來接收校驗結果。

分組校驗

舉個例子：上傳文章不需要傳文章ID，但是修改文章需要上傳文章ID，並且用的都是同一個DTO接收引數，此時的約束條件該如何寫呢？

此時就需要對這個文章ID進行分組校驗，上傳文章介面是一個分組，不需要執行@NotNull校驗，修改文章的介面是一個分組，需要執行@NotNull的校驗。

所有的校驗註解都有一個groups屬性用來指定分組，Class<?>[]型別，沒有實際意義，因此只需要定義一個或者多個介面用來區分即可。

@Data
public class ArticleDTO {

    /**
     * 文章ID只在修改的時候需要檢驗，因此指定groups為修改的分組
     */
    @NotNull(message = "文章id不能為空",groups = UpdateArticleDTO.class )
    @Min(value = 1,message = "文章ID不能為負數",groups = UpdateArticleDTO.class)
    private Integer id;

    /**
     * 文章內容新增和修改都是必須校驗的，groups需要指定兩個分組
     */
    @NotBlank(message = "文章內容不能為空",groups = {AddArticleDTO.class,UpdateArticleDTO.class})
    private String content;

    @NotBlank(message = "作者Id不能為空",groups = AddArticleDTO.class)
    private String authorId;

    /**
     * 提交時間是新增和修改都需要校驗的，因此指定groups兩個
     */
    @Future(message = "提交時間不能為過去時間",groups = {AddArticleDTO.class,UpdateArticleDTO.class})
    private Date submitTime;
    
    //修改文章的分組
    public interface UpdateArticleDTO{}

    //新增文章的分組
    public interface AddArticleDTO{}

}

JSR303本身的@Valid並不支援分組校驗，但是Spring在其基礎提供了一個註解@Validated支援分組校驗。@Validated這個註解value屬性指定需要校驗的分組。

/**
     * 新增文章
     * @Validated：這個註解指定校驗的分組資訊
     */
    @PostMapping("/add")
    public String add(@Validated(value = ArticleDTO.AddArticleDTO.class) @RequestBody ArticleDTO articleDTO, BindingResult bindingResult) throws JsonProcessingException {
        //如果有錯誤提示資訊
        if (bindingResult.hasErrors()) {
            Map<String , String> map = new HashMap<>();
            bindingResult.getFieldErrors().forEach( (item) -> {
                String message = item.getDefaultMessage();
                String field = item.getField();
                map.put( field , message );
            } );
            //返回提示資訊
            return objectMapper.writeValueAsString(map);
        }
        return "success";
    }

巢狀校驗

巢狀校驗簡單的解釋就是一個實體中包含另外一個實體，並且這兩個或者多個實體都需要校驗。

舉個例子：文章可以有一個或者多個分類，作者在提交文章的時候必須指定文章分類，而分類是單獨一個實體，有分類ID、名稱等等。大致的結構如下：

public class ArticleDTO{
  ...文章的一些屬性.....
  
  //分類的資訊
  private CategoryDTO categoryDTO;
}

此時文章和分類的屬性都需要校驗，這種就叫做巢狀校驗。

巢狀校驗很簡單，只需要在巢狀的實體屬性標註@Valid註解，則其中的屬性也將會得到校驗，否則不會校驗。

如下文章分類實體類校驗：

/**
 * 文章分類
 */
@Data
public class CategoryDTO {
    @NotNull(message = "分類ID不能為空")
    @Min(value = 1,message = "分類ID不能為負數")
    private Integer id;

    @NotBlank(message = "分類名稱不能為空")
    private String name;
}

文章的實體類中有個巢狀的文章分類CategoryDTO屬性，需要使用@Valid標註才能巢狀校驗，如下：

@Data
public class ArticleDTO {

    @NotBlank(message = "文章內容不能為空")
    private String content;

    @NotBlank(message = "作者Id不能為空")
    private String authorId;

    @Future(message = "提交時間不能為過去時間")
    private Date submitTime;

    /**
     * @Valid這個註解指定CategoryDTO中的屬性也需要校驗
     */
    @Valid
    @NotNull(message = "分類不能為空")
    private CategoryDTO categoryDTO;
  }

Controller層的新增文章的介面同上，需要使用@Valid或者@Validated標註入參，同時需要定義一個BindingResult的引數接收校驗結果。

巢狀校驗針對分組查詢仍然生效，如果巢狀的實體類（比如CategoryDTO）中的校驗的屬性和介面中@Validated註解指定的分組不同，則不會校驗。

JSR-303針對集合的巢狀校驗也是可行的，比如List的巢狀校驗，同樣需要在屬性上標註一個@Valid註解才會生效，如下：

@Data
public class ArticleDTO {
    /**
     * @Valid這個註解標註在集合上，將會針對集合中每個元素進行校驗
     */
    @Valid
    @Size(min = 1,message = "至少一個分類")
    @NotNull(message = "分類不能為空")
    private List<CategoryDTO> categoryDTOS;
  }

總結：巢狀校驗只需要在需要校驗的元素（單個或者集合）上新增@Valid註解，介面層需要使用@Valid或者@Validated註解標註入參。

如何接收校驗結果？

接收校驗的結果的方式很多，不過實際開發中最好選擇一個優雅的方式，下面介紹常見的兩種方式。

BindingResult 接收

這種方式需要在Controller層的每個介面方法引數中指定，Validator會將校驗的資訊自動封裝到其中。這也是上面例子中一直用的方式。如下：

@PostMapping("/add")
    public String add(@Valid @RequestBody ArticleDTO articleDTO, BindingResult bindingResult){}

這種方式的弊端很明顯，每個介面方法引數都要宣告，同時每個方法都要處理校驗資訊，顯然不現實，捨棄。

此種方式還有一個優化的方案：使用AOP，在Controller介面方法執行之前處理BindingResult的訊息提示，不過這種方案仍然不推薦使用。

全域性異常捕捉

引數在校驗失敗的時候會丟擲的MethodArgumentNotValidException或者BindException兩種異常，可以在全域性的異常處理器中捕捉到這兩種異常，將提示資訊或者自定義資訊返回給客戶端。

全域性異常捕捉之前有單獨寫過一篇文章，不理解的可以看滿屏的try-catch，你不瘮得慌？。

作者這裡就不再詳細的貼出其他的異常捕獲了，僅僅貼一下引數校驗的異常捕獲（僅僅舉個例子，具體的返回資訊需要自己封裝），如下：

@RestControllerAdvice
public class ExceptionRsHandler {

    @Autowired
    private ObjectMapper objectMapper;

    /**
     * 引數校驗異常步驟
     */
    @ExceptionHandler(value= {MethodArgumentNotValidException.class , BindException.class})
    public String onException(Exception e) throws JsonProcessingException {
        BindingResult bindingResult = null;
        if (e instanceof MethodArgumentNotValidException) {
            bindingResult = ((MethodArgumentNotValidException)e).getBindingResult();
        } else if (e instanceof BindException) {
            bindingResult = ((BindException)e).getBindingResult();
        }
        Map<String,String> errorMap = new HashMap<>(16);
        bindingResult.getFieldErrors().forEach((fieldError)->
                errorMap.put(fieldError.getField(),fieldError.getDefaultMessage())
        );
        return objectMapper.writeValueAsString(errorMap);
    }

}

spring-boot-starter-validation做了什麼？

這個啟動器的自動配置類是ValidationAutoConfiguration，最重要的程式碼就是注入了一個Validator（校驗器）的實現類，程式碼如下：

@Bean
 @Role(BeanDefinition.ROLE_INFRASTRUCTURE)
 @ConditionalOnMissingBean(Validator.class)
 public static LocalValidatorFactoryBean defaultValidator() {
  LocalValidatorFactoryBean factoryBean = new LocalValidatorFactoryBean();
  MessageInterpolatorFactory interpolatorFactory = new MessageInterpolatorFactory();
  factoryBean.setMessageInterpolator(interpolatorFactory.getObject());
  return factoryBean;
 }

這個有什麼用呢？Validator這個介面定義了校驗的方法，如下：

<T> Set<ConstraintViolation<T>> validate(T object, Class<?>... groups);


<T> Set<ConstraintViolation<T>> validateProperty(T object,
              String propertyName,
              Class<?>... groups);
                           
<T> Set<ConstraintViolation<T>> validateValue(Class<T> beanType,
              String propertyName,
              Object value,
              Class<?>... groups);
......

這個Validator可以用來自定義實現自己的校驗邏輯，有些大公司完全不用JSR-303提供的@Valid註解，而是有一套自己的實現，其實本質就是利用Validator這個介面的實現。

如何自定義校驗？

雖說在日常的開發中內建的約束註解已經夠用了，但是仍然有些時候不能滿足需求，需要自定義一些校驗約束。

舉個例子：有這樣一個例子，傳入的數字要在列舉的值範圍中，否則校驗失敗。

自定義校驗註解

首先需要自定義一個校驗註解，如下：

@Documented
@Constraint(validatedBy = { EnumValuesConstraintValidator.class})
@Target({ METHOD, FIELD, ANNOTATION_TYPE })
@Retention(RUNTIME)
@NotNull(message = "不能為空")
public @interface EnumValues {
    /**
     * 提示訊息
     */
    String message() default "傳入的值不在範圍內";

    /**
     * 分組
     * @return
     */
    Class<?>[] groups() default { };

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

    /**
     * 可以傳入的值
     * @return
     */
    int[] values() default { };
}

根據Bean Validation API 規範的要求有如下三個屬性是必須的：

1. message：定義訊息模板，校驗失敗時輸出
2. groups：用於校驗分組
3. payload：Bean Validation API 的使用者可以通過此屬性來給約束條件指定嚴重級別. 這個屬性並不被API自身所使用。

除了以上三個必須要的屬性，新增了一個values屬性用來接收限制的範圍。

該校驗註解頭上標註的如下一行程式碼：

@Constraint(validatedBy = { EnumValuesConstraintValidator.class})

這個@Constraint註解指定了通過哪個校驗器去校驗。

自定義校驗註解可以複用內嵌的註解，比如@EnumValues註解頭上標註了一個@NotNull註解，這樣@EnumValues就兼具了@NotNull的功能。

自定義校驗器

@Constraint註解指定了校驗器為EnumValuesConstraintValidator，因此需要自定義一個。

自定義校驗器需要實現ConstraintValidator<A extends Annotation, T>這個介面，第一個泛型是校驗註解，第二個是引數型別。程式碼如下：

/**
 * 校驗器
 */
public class EnumValuesConstraintValidator implements ConstraintValidator<EnumValues,Integer> {
    /**
     * 儲存列舉的值
     */
    private  Set<Integer> ints=new HashSet<>();

    /**
     * 初始化方法
     * @param enumValues 校驗的註解
     */
    @Override
    public void initialize(EnumValues enumValues) {
        for (int value : enumValues.values()) {
            ints.add(value);
        }
    }

    /**
     *
     * @param value  入參傳的值
     * @param context
     * @return
     */
    @Override
    public boolean isValid(Integer value, ConstraintValidatorContext context) {
        //判斷是否包含這個值
        return ints.contains(value);
    }
}

如果約束註解需要對其他資料型別進行校驗，則可以的自定義對應資料型別的校驗器，然後在約束註解頭上的@Constraint註解中指定其他的校驗器。

演示

校驗註解和校驗器自定義成功之後即可使用，如下：

@Data
public class AuthorDTO {
    @EnumValues(values = {1,2},message = "性別只能傳入1或者2")
    private Integer gender;
}

總結

資料校驗作為客戶端和服務端的一道屏障，有著重要的作用，通過這篇文章希望能夠對JSR-303資料校驗有著全面的認識。