工作幾年了，原來只用了數(shù)據(jù)校驗的皮毛
前言
不知不覺Spring Boot專欄文章已經(jīng)寫到第十四章了，無論寫的好與不好，作者都在盡力寫的詳細(xì)，寫的與其它的文章不同，每一章都不是淺嘗輒止。如果前面的文章沒有看過的朋友，點(diǎn)擊這里前往。
今天介紹一下 Spring Boot 如何優(yōu)雅的整合JSR-303進(jìn)行參數(shù)校驗，說到參數(shù)校驗可能都用過，但是你真的會用嗎？網(wǎng)上的教程很多，大多是簡單的介紹。
什么是 JSR-303？
JSR-303 是 JAVA EE 6 中的一項子規(guī)范，叫做 Bean Validation。
Bean Validation 為 JavaBean 驗證定義了相應(yīng)的元數(shù)據(jù)模型和API。缺省的元數(shù)據(jù)是Java Annotations，通過使用 XML 可以對原有的元數(shù)據(jù)信息進(jìn)行覆蓋和擴(kuò)展。在應(yīng)用程序中，通過使用Bean Validation 或是你自己定義的 constraint，例如 @NotNull, @Max, @ZipCode ， 就可以確保數(shù)據(jù)模型（JavaBean）的正確性。constraint 可以附加到字段，getter 方法，類或者接口上面。對于一些特定的需求，用戶可以很容易的開發(fā)定制化的 constraint。Bean Validation 是一個運(yùn)行時的數(shù)據(jù)驗證框架，在驗證之后驗證的錯誤信息會被馬上返回。
添加依賴
Spring Boot整合JSR-303只需要添加一個starter即可，如下：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>內(nèi)嵌的注解有哪些？
Bean Validation 內(nèi)嵌的注解很多，基本實際開發(fā)中已經(jīng)夠用了，注解如下：
注解 | 詳細(xì)信息 |
@Null | 被注釋的元素必須為 null |
@NotNull | 被注釋的元素必須不為 null |
@AssertTrue | 被注釋的元素必須為 true |
@AssertFalse | 被注釋的元素必須為 false |
@Min(value) | 被注釋的元素必須是一個數(shù)字，其值必須大于等于指定的最小值 |
@Max(value) | 被注釋的元素必須是一個數(shù)字，其值必須小于等于指定的最大值 |
@DecimalMin(value) | 被注釋的元素必須是一個數(shù)字，其值必須大于等于指定的最小值 |
@DecimalMax(value) | 被注釋的元素必須是一個數(shù)字，其值必須小于等于指定的最大值 |
@Size(max, min) | 被注釋的元素的大小必須在指定的范圍內(nèi) |
@Digits (integer, fraction) | 被注釋的元素必須是一個數(shù)字，其值必須在可接受的范圍內(nèi) |
@Past | 被注釋的元素必須是一個過去的日期 |
@Future | 被注釋的元素必須是一個將來的日期 |
@Pattern(value) | 被注釋的元素必須符合指定的正則表達(dá)式 |
以上是Bean Validation的內(nèi)嵌的注解，但是Hibernate Validator在原有的基礎(chǔ)上也內(nèi)嵌了幾個注解，如下。
注解 | 詳細(xì)信息 |
被注釋的元素必須是電子郵箱地址 | |
@Length | 被注釋的字符串的大小必須在指定的范圍內(nèi) |
@NotEmpty | 被注釋的字符串的必須非空 |
@Range | 被注釋的元素必須在合適的范圍內(nèi) |
如何使用？
參數(shù)校驗分為簡單校驗、嵌套校驗、分組校驗。
簡單校驗
簡單的校驗即是沒有嵌套屬性，直接在需要的元素上標(biāo)注約束注解即可。如下：
@Data
publicclass 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 = "提交時間不能為過去時間")
private Date submitTime;
}同一個屬性可以指定多個約束，比如@NotNull和@MAX,其中的message屬性指定了約束條件不滿足時的提示信息。
以上約束標(biāo)記完成之后，要想完成校驗，需要在controller層的接口標(biāo)注@Valid注解以及聲明一個BindingResult類型的參數(shù)來接收校驗的結(jié)果。
下面簡單的演示下添加文章的接口，如下：
/**
* 添加文章
*/
@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";
}僅僅在屬性上添加了約束注解還不行，還需在接口參數(shù)上標(biāo)注@Valid注解并且聲明一個BindingResult類型的參數(shù)來接收校驗結(jié)果。
分組校驗
舉個栗子：上傳文章不需要傳文章ID，但是修改文章需要上傳文章ID，并且用的都是同一個DTO接收參數(shù)，此時的約束條件該如何寫呢？
此時就需要對這個文章ID進(jìn)行分組校驗，上傳文章接口是一個分組，不需要執(zhí)行@NotNull校驗，修改文章的接口是一個分組，需要執(zhí)行@NotNull的校驗。
所有的校驗注解都有一個groups屬性用來指定分組，Class<?>[]類型，沒有實際意義，因此只需要定義一個或者多個接口用來區(qū)分即可。
@Data
publicclass ArticleDTO {
/**
* 文章ID只在修改的時候需要檢驗，因此指定groups為修改的分組
*/
@NotNull(message = "文章id不能為空",groups = UpdateArticleDTO.class )
@Min(value = 1,message = "文章ID不能為負(fù)數(shù)",groups = UpdateArticleDTO.class)
private Integer id;
/**
* 文章內(nèi)容添加和修改都是必須校驗的，groups需要指定兩個分組
*/
@NotBlank(message = "文章內(nèi)容不能為空",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;
//修改文章的分組
publicinterface UpdateArticleDTO{}
//添加文章的分組
publicinterface AddArticleDTO{}
}JSR303本身的@Valid并不支持分組校驗，但是Spring在其基礎(chǔ)提供了一個注解@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";
}嵌套校驗
嵌套校驗簡單的解釋就是一個實體中包含另外一個實體，并且這兩個或者多個實體都需要校驗。
舉個栗子：文章可以有一個或者多個分類，作者在提交文章的時候必須指定文章分類，而分類是單獨(dú)一個實體，有分類ID、名稱等等。大致的結(jié)構(gòu)如下：
public class ArticleDTO{
...文章的一些屬性.....
//分類的信息
private CategoryDTO categoryDTO;
}此時文章和分類的屬性都需要校驗，這種就叫做嵌套校驗。
嵌套校驗很簡單，只需要在嵌套的實體屬性標(biāo)注@Valid注解，則其中的屬性也將會得到校驗，否則不會校驗。
如下文章分類實體類校驗：
/**
* 文章分類
*/
@Data
public class CategoryDTO {
@NotNull(message = "分類ID不能為空")
@Min(value = 1,message = "分類ID不能為負(fù)數(shù)")
private Integer id;
@NotBlank(message = "分類名稱不能為空")
private String name;
}文章的實體類中有個嵌套的文章分類CategoryDTO屬性，需要使用@Valid標(biāo)注才能嵌套校驗，如下：
@Data
publicclass ArticleDTO {
@NotBlank(message = "文章內(nèi)容不能為空")
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標(biāo)注入?yún)ⅲ瑫r需要定義一個BindingResult的參數(shù)接收校驗結(jié)果。
嵌套校驗針對分組查詢?nèi)匀簧В绻短椎膶嶓w類（比如CategoryDTO）中的校驗的屬性和接口中@Validated注解指定的分組不同，則不會校驗。
JSR-303針對集合的嵌套校驗也是可行的，比如List的嵌套校驗，同樣需要在屬性上標(biāo)注一個@Valid注解才會生效，如下：
@Data
public class ArticleDTO {
/**
* @Valid這個注解標(biāo)注在集合上，將會針對集合中每個元素進(jìn)行校驗
*/
@Valid
@Size(min = 1,message = "至少一個分類")
@NotNull(message = "分類不能為空")
private List<CategoryDTO> categoryDTOS;
}總結(jié)：嵌套校驗只需要在需要校驗的元素（單個或者集合）上添加@Valid注解，接口層需要使用@Valid或者@Validated注解標(biāo)注入?yún)ⅰ?/p>
如何接收校驗結(jié)果？
接收校驗的結(jié)果的方式很多，不過實際開發(fā)中最好選擇一個優(yōu)雅的方式，下面介紹常見的兩種方式。
BindingResult 接收
這種方式需要在Controller層的每個接口方法參數(shù)中指定，Validator會將校驗的信息自動封裝到其中。這也是上面例子中一直用的方式。如下：
@PostMapping("/add")
public String add(@Valid @RequestBody ArticleDTO articleDTO, BindingResult bindingResult){}這種方式的弊端很明顯，每個接口方法參數(shù)都要聲明，同時每個方法都要處理校驗信息，顯然不現(xiàn)實，舍棄。
此種方式還有一個優(yōu)化的方案：使用AOP，在Controller接口方法執(zhí)行之前處理BindingResult的消息提示，不過這種方案仍然不推薦使用。
全局異常捕捉
參數(shù)在校驗失敗的時候會拋出的MethodArgumentNotValidException或者BindException兩種異常，可以在全局的異常處理器中捕捉到這兩種異常，將提示信息或者自定義信息返回給客戶端。
全局異常捕捉之前有單獨(dú)寫過一篇文章，不理解的可以看滿屏的try-catch，你不瘆得慌？。
作者這里就不再詳細(xì)的貼出其他的異常捕獲了，僅僅貼一下參數(shù)校驗的異常捕獲（僅僅舉個例子，具體的返回信息需要自己封裝），如下：
@RestControllerAdvice
publicclass ExceptionRsHandler {
@Autowired
private ObjectMapper objectMapper;
/**
* 參數(shù)校驗異常步驟
*/
@ExceptionHandler(value= {MethodArgumentNotValidException.class , BindException.class})
public String onException(Exception e) throws JsonProcessingException {
BindingResult bindingResult = null;
if (e instanceof MethodArgumentNotValidException) {
bindingResult = ((MethodArgumentNotValidException)e).getBindingResult();
} elseif (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（校驗器）的實現(xiàn)類，代碼如下：
@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可以用來自定義實現(xiàn)自己的校驗邏輯，有些大公司完全不用JSR-303提供的@Valid注解，而是有一套自己的實現(xiàn)，其實本質(zhì)就是利用Validator這個接口的實現(xiàn)。
如何自定義校驗？
雖說在日常的開發(fā)中內(nèi)置的約束注解已經(jīng)夠用了，但是仍然有些時候不能滿足需求，需要自定義一些校驗約束。
舉個栗子：有這樣一個例子，傳入的數(shù)字要在列舉的值范圍中，否則校驗失敗。
自定義校驗注解
首先需要自定義一個校驗注解，如下：
@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<? extends Payload>[] payload() default { };
/**
* 可以傳入的值
* @return
*/
int[] values() default { };
}根據(jù)Bean Validation API 規(guī)范的要求有如下三個屬性是必須的：
- message：定義消息模板，校驗失敗時輸出
- groups：用于校驗分組
- payload：Bean Validation API 的使用者可以通過此屬性來給約束條件指定嚴(yán)重級別. 這個屬性并不被API自身所使用。
除了以上三個必須要的屬性，添加了一個values屬性用來接收限制的范圍。
該校驗注解頭上標(biāo)注的如下一行代碼：
@Constraint(validatedBy = { EnumValuesConstraintValidator.class})這個@Constraint注解指定了通過哪個校驗器去校驗。
自定義校驗注解可以復(fù)用內(nèi)嵌的注解，比如@EnumValues注解頭上標(biāo)注了一個@NotNull注解，這樣@EnumValues就兼具了@NotNull的功能。
自定義校驗器
@Constraint注解指定了校驗器為EnumValuesConstraintValidator，因此需要自定義一個。
自定義校驗器需要實現(xiàn)ConstraintValidator<A extends Annotation, T>這個接口，第一個泛型是校驗注解，第二個是參數(shù)類型。代碼如下：
/**
* 校驗器
*/
publicclass 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 入?yún)鞯闹? * @param context
* @return
*/
@Override
public boolean isValid(Integer value, ConstraintValidatorContext context) {
//判斷是否包含這個值
return ints.contains(value);
}
}如果約束注解需要對其他數(shù)據(jù)類型進(jìn)行校驗，則可以的自定義對應(yīng)數(shù)據(jù)類型的校驗器，然后在約束注解頭上的@Constraint注解中指定其他的校驗器。
演示
校驗注解和校驗器自定義成功之后即可使用，如下：
@Data
public class AuthorDTO {
@EnumValues(values = {1,2},message = "性別只能傳入1或者2")
private Integer gender;
}總結(jié)
數(shù)據(jù)校驗作為客戶端和服務(wù)端的一道屏障，有著重要的作用，通過這篇文章希望能夠?qū)SR-303數(shù)據(jù)校驗有著全面的認(rèn)識。
