工作幾年了，原來(lái)我只用了數(shù)據(jù)校驗(yàn)的皮毛

今天介紹一下 Spring Boot 如何優(yōu)雅的整合JSR-303進(jìn)行參數(shù)校驗(yàn)，說(shuō)到參數(shù)校驗(yàn)可能都用過(guò)，但是你真的會(huì)用嗎？網(wǎng)上的教程很多，大多是簡(jiǎn)單的介紹。

什么是 JSR-303？

JSR-303 是 JAVA EE 6 中的一項(xiàng)子規(guī)范，叫做 Bean Validation。

Bean Validation 為 JavaBean 驗(yàn)證定義了相應(yīng)的元數(shù)據(jù)模型和API。缺省的元數(shù)據(jù)是Java Annotations，通過(guò)使用 XML 可以對(duì)原有的元數(shù)據(jù)信息進(jìn)行覆蓋和擴(kuò)展。在應(yīng)用程序中，通過(guò)使用Bean Validation 或是你自己定義的 constraint，例如 @NotNull, @Max, @ZipCode ， 就可以確保數(shù)據(jù)模型（JavaBean）的正確性。constraint 可以附加到字段，getter 方法，類(lèi)或者接口上面。對(duì)于一些特定的需求，用戶可以很容易的開(kāi)發(fā)定制化的 constraint。Bean Validation 是一個(gè)運(yùn)行時(shí)的數(shù)據(jù)驗(yàn)證框架，在驗(yàn)證之后驗(yàn)證的錯(cuò)誤信息會(huì)被馬上返回。

添加依賴

Spring Boot整合JSR-303只需要添加一個(gè)starter即可，如下：

<dependency>
????<groupId>org.springframework.bootgroupId>
???<artifactId>spring-boot-starter-validationartifactId>
dependency>

內(nèi)嵌的注解有哪些？

Bean Validation 內(nèi)嵌的注解很多，基本實(shí)際開(kāi)發(fā)中已經(jīng)夠用了，注解如下：

以上是Bean Validation的內(nèi)嵌的注解，但是Hibernate Validator在原有的基礎(chǔ)上也內(nèi)嵌了幾個(gè)注解，如下。

如何使用？

參數(shù)校驗(yàn)分為簡(jiǎn)單校驗(yàn)、嵌套校驗(yàn)、分組校驗(yàn)。

簡(jiǎn)單校驗(yàn)

簡(jiǎn)單的校驗(yàn)即是沒(méi)有嵌套屬性，直接在需要的元素上標(biāo)注約束注解即可。如下：

@Data
public?class?ArticleDTO?{

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

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

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

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

同一個(gè)屬性可以指定多個(gè)約束，比如@NotNull和@MAX,其中的message屬性指定了約束條件不滿足時(shí)的提示信息。

以上約束標(biāo)記完成之后，要想完成校驗(yàn)，需要在controller層的接口標(biāo)注@Valid注解以及聲明一個(gè)BindingResult類(lèi)型的參數(shù)來(lái)接收校驗(yàn)的結(jié)果。

下面簡(jiǎn)單的演示下添加文章的接口，如下：

/**
?????*?添加文章
?????*/
????@PostMapping("/add")
????public?String?add(@Valid?@RequestBody?ArticleDTO?articleDTO,?BindingResult?bindingResult)?throws?JsonProcessingException?{
????????//如果有錯(cuò)誤提示信息
????????if?(bindingResult.hasErrors())?{
????????????Map?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";
????}

僅僅在屬性上添加了約束注解還不行，還需在接口參數(shù)上標(biāo)注@Valid注解并且聲明一個(gè)BindingResult類(lèi)型的參數(shù)來(lái)接收校驗(yàn)結(jié)果。

分組校驗(yàn)

舉個(gè)栗子：上傳文章不需要傳文章ID，但是修改文章需要上傳文章ID，并且用的都是同一個(gè)DTO接收參數(shù)，此時(shí)的約束條件該如何寫(xiě)呢？

此時(shí)就需要對(duì)這個(gè)文章ID進(jìn)行分組校驗(yàn)，上傳文章接口是一個(gè)分組，不需要執(zhí)行@NotNull校驗(yàn)，修改文章的接口是一個(gè)分組，需要執(zhí)行@NotNull的校驗(yàn)。

所有的校驗(yàn)注解都有一個(gè)groups屬性用來(lái)指定分組，Class[]類(lèi)型，沒(méi)有實(shí)際意義，因此只需要定義一個(gè)或者多個(gè)接口用來(lái)區(qū)分即可。

@Data
public?class?ArticleDTO?{

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

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

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

????/**
?????*?提交時(shí)間是添加和修改都需要校驗(yàn)的，因此指定groups兩個(gè)
?????*/
????@Future(message?=?"提交時(shí)間不能為過(guò)去時(shí)間",groups?=?{AddArticleDTO.class,UpdateArticleDTO.class})
????private?Date?submitTime;
????
????//修改文章的分組
????public?interface?UpdateArticleDTO{}

????//添加文章的分組
????public?interface?AddArticleDTO{}

}

JSR303本身的@Valid并不支持分組校驗(yàn)，但是Spring在其基礎(chǔ)提供了一個(gè)注解@Validated支持分組校驗(yàn)。@Validated這個(gè)注解value屬性指定需要校驗(yàn)的分組。

/**
?????*?添加文章
?????*?@Validated：這個(gè)注解指定校驗(yàn)的分組信息
?????*/
????@PostMapping("/add")
????public?String?add(@Validated(value?=?ArticleDTO.AddArticleDTO.class)?@RequestBody?ArticleDTO?articleDTO,?BindingResult?bindingResult)?throws?JsonProcessingException?{
????????//如果有錯(cuò)誤提示信息
????????if?(bindingResult.hasErrors())?{
????????????Map?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";
????}

嵌套校驗(yàn)

嵌套校驗(yàn)簡(jiǎn)單的解釋就是一個(gè)實(shí)體中包含另外一個(gè)實(shí)體，并且這兩個(gè)或者多個(gè)實(shí)體都需要校驗(yàn)。

舉個(gè)栗子：文章可以有一個(gè)或者多個(gè)分類(lèi)，作者在提交文章的時(shí)候必須指定文章分類(lèi)，而分類(lèi)是單獨(dú)一個(gè)實(shí)體，有分類(lèi)ID、名稱(chēng)等等。大致的結(jié)構(gòu)如下：

public?class?ArticleDTO{
??...文章的一些屬性.....
??
??//分類(lèi)的信息
??private?CategoryDTO?categoryDTO;
}

此時(shí)文章和分類(lèi)的屬性都需要校驗(yàn)，這種就叫做嵌套校驗(yàn)。

嵌套校驗(yàn)很簡(jiǎn)單，只需要在嵌套的實(shí)體屬性標(biāo)注@Valid注解，則其中的屬性也將會(huì)得到校驗(yàn)，否則不會(huì)校驗(yàn)。

如下文章分類(lèi)實(shí)體類(lèi)校驗(yàn)：

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

????@NotBlank(message?=?"分類(lèi)名稱(chēng)不能為空")
????private?String?name;
}

文章的實(shí)體類(lèi)中有個(gè)嵌套的文章分類(lèi)CategoryDTO屬性，需要使用@Valid標(biāo)注才能嵌套校驗(yàn)，如下：

@Data
public?class?ArticleDTO?{

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

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

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

????/**
?????*?@Valid這個(gè)注解指定CategoryDTO中的屬性也需要校驗(yàn)
?????*/
????@Valid
????@NotNull(message?=?"分類(lèi)不能為空")
????private?CategoryDTO?categoryDTO;
??}

Controller層的添加文章的接口同上，需要使用@Valid或者@Validated標(biāo)注入?yún)?，同時(shí)需要定義一個(gè)BindingResult的參數(shù)接收校驗(yàn)結(jié)果。

嵌套校驗(yàn)針對(duì)分組查詢仍然生效，如果嵌套的實(shí)體類(lèi)（比如CategoryDTO）中的校驗(yàn)的屬性和接口中@Validated注解指定的分組不同，則不會(huì)校驗(yàn)。

JSR-303針對(duì)集合的嵌套校驗(yàn)也是可行的，比如List的嵌套校驗(yàn)，同樣需要在屬性上標(biāo)注一個(gè)@Valid注解才會(huì)生效，如下：

@Data
public?class?ArticleDTO?{
????/**
?????*?@Valid這個(gè)注解標(biāo)注在集合上，將會(huì)針對(duì)集合中每個(gè)元素進(jìn)行校驗(yàn)
?????*/
????@Valid
????@Size(min?=?1,message?=?"至少一個(gè)分類(lèi)")
????@NotNull(message?=?"分類(lèi)不能為空")
????private?List?categoryDTOS;
??}

總結(jié)：嵌套校驗(yàn)只需要在需要校驗(yàn)的元素（單個(gè)或者集合）上添加@Valid注解，接口層需要使用@Valid或者@Validated注解標(biāo)注入?yún)ⅰ?/p>

如何接收校驗(yàn)結(jié)果？

接收校驗(yàn)的結(jié)果的方式很多，不過(guò)實(shí)際開(kāi)發(fā)中最好選擇一個(gè)優(yōu)雅的方式，下面介紹常見(jiàn)的兩種方式。

BindingResult 接收

這種方式需要在Controller層的每個(gè)接口方法參數(shù)中指定，Validator會(huì)將校驗(yàn)的信息自動(dòng)封裝到其中。這也是上面例子中一直用的方式。如下：

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

這種方式的弊端很明顯，每個(gè)接口方法參數(shù)都要聲明，同時(shí)每個(gè)方法都要處理校驗(yàn)信息，顯然不現(xiàn)實(shí)，舍棄。

此種方式還有一個(gè)優(yōu)化的方案：使用AOP，在Controller接口方法執(zhí)行之前處理BindingResult的消息提示，不過(guò)這種方案仍然不推薦使用。

全局異常捕捉

參數(shù)在校驗(yàn)失敗的時(shí)候會(huì)拋出的MethodArgumentNotValidException或者BindException兩種異常，可以在全局的異常處理器中捕捉到這兩種異常，將提示信息或者自定義信息返回給客戶端。

全局異常捕捉之前有單獨(dú)寫(xiě)過(guò)一篇文章，不理解的可以看滿屏的try-catch，你不瘆得慌？。

作者這里就不再詳細(xì)的貼出其他的異常捕獲了，僅僅貼一下參數(shù)校驗(yàn)的異常捕獲（僅僅舉個(gè)例子，具體的返回信息需要自己封裝），如下：

@RestControllerAdvice
public?class?ExceptionRsHandler?{

????@Autowired
????private?ObjectMapper?objectMapper;

????/**
?????*?參數(shù)校驗(yàn)異常步驟
?????*/
????@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?errorMap?=?new?HashMap<>(16);
????????bindingResult.getFieldErrors().forEach((fieldError)->
????????????????errorMap.put(fieldError.getField(),fieldError.getDefaultMessage())
????????);
????????return?objectMapper.writeValueAsString(errorMap);
????}

}

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

這個(gè)啟動(dòng)器的自動(dòng)配置類(lèi)是ValidationAutoConfiguration，最重要的代碼就是注入了一個(gè)Validator（校驗(yàn)器）的實(shí)現(xiàn)類(lèi)，代碼如下：

@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;
?}

這個(gè)有什么用呢？Validator這個(gè)接口定義了校驗(yàn)的方法，如下：

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


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

這個(gè)Validator可以用來(lái)自定義實(shí)現(xiàn)自己的校驗(yàn)邏輯，有些大公司完全不用JSR-303提供的@Valid注解，而是有一套自己的實(shí)現(xiàn)，其實(shí)本質(zhì)就是利用Validator這個(gè)接口的實(shí)現(xiàn)。

如何自定義校驗(yàn)？

雖說(shuō)在日常的開(kāi)發(fā)中內(nèi)置的約束注解已經(jīng)夠用了，但是仍然有些時(shí)候不能滿足需求，需要自定義一些校驗(yàn)約束。

舉個(gè)栗子：有這樣一個(gè)例子，傳入的數(shù)字要在列舉的值范圍中，否則校驗(yàn)失敗。

自定義校驗(yàn)注解

首先需要自定義一個(gè)校驗(yàn)注解，如下：

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

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

????Class[]?payload()?default?{?};

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

根據(jù)Bean Validation API 規(guī)范的要求有如下三個(gè)屬性是必須的：

1. message：定義消息模板，校驗(yàn)失敗時(shí)輸出
2. groups：用于校驗(yàn)分組
3. payload：Bean Validation API 的使用者可以通過(guò)此屬性來(lái)給約束條件指定嚴(yán)重級(jí)別. 這個(gè)屬性并不被API自身所使用。

除了以上三個(gè)必須要的屬性，添加了一個(gè)values屬性用來(lái)接收限制的范圍。

該校驗(yàn)注解頭上標(biāo)注的如下一行代碼：

@Constraint(validatedBy?=?{?EnumValuesConstraintValidator.class})

這個(gè)@Constraint注解指定了通過(guò)哪個(gè)校驗(yàn)器去校驗(yàn)。

自定義校驗(yàn)注解可以復(fù)用內(nèi)嵌的注解，比如@EnumValues注解頭上標(biāo)注了一個(gè)@NotNull注解，這樣@EnumValues就兼具了@NotNull的功能。

自定義校驗(yàn)器

@Constraint注解指定了校驗(yàn)器為EnumValuesConstraintValidator，因此需要自定義一個(gè)。

自定義校驗(yàn)器需要實(shí)現(xiàn)ConstraintValidator這個(gè)接口，第一個(gè)泛型是校驗(yàn)注解，第二個(gè)是參數(shù)類(lèi)型。代碼如下：

/**
?*?校驗(yàn)器
?*/
public?class?EnumValuesConstraintValidator?implements?ConstraintValidator<EnumValues,Integer>?{
????/**
?????*?存儲(chǔ)枚舉的值
?????*/
????private??Set?ints=new?HashSet<>();

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

????/**
?????*
?????*?@param?value??入?yún)鞯闹?br>?????*?@param?context
?????*?@return
?????*/
????@Override
????public?boolean?isValid(Integer?value,?ConstraintValidatorContext?context)?{
????????//判斷是否包含這個(gè)值
????????return?ints.contains(value);
????}
}

如果約束注解需要對(duì)其他數(shù)據(jù)類(lèi)型進(jìn)行校驗(yàn)，則可以的自定義對(duì)應(yīng)數(shù)據(jù)類(lèi)型的校驗(yàn)器，然后在約束注解頭上的@Constraint注解中指定其他的校驗(yàn)器。

演示

校驗(yàn)注解和校驗(yàn)器自定義成功之后即可使用，如下：

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

總結(jié)

數(shù)據(jù)校驗(yàn)作為客戶端和服務(wù)端的一道屏障，有著重要的作用，通過(guò)這篇文章希望能夠?qū)?code style="font-size: 14px;padding: 2px 4px;border-radius: 4px;margin-right: 2px;margin-left: 2px;background-color: rgba(27, 31, 35, 0.05);font-family: "Operator Mono", Consolas, Monaco, Menlo, monospace;word-break: break-all;color: rgb(40, 202, 113);">JSR-303數(shù)據(jù)校驗(yàn)有著全面的認(rèn)識(shí)。