springboot引數校驗最全的帖子
https://www.cnblogs.com/Chenjiabing/p/13890384.html
今天介紹一下 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
在原有的基礎上也內嵌了幾個註解,如下。
註解 | 詳細資訊 |
---|---|
被註釋的元素必須是電子郵箱地址 | |
@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
規範的要求有如下三個屬性是必須的:
message
:定義訊息模板,校驗失敗時輸出groups
:用於校驗分組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
資料校驗有著全面的認識。