使用Spring Validation優雅地校驗引數
阿新 • • 發佈：2020-07-29
> 寫得好的沒我寫得全，寫得全的沒我寫得好
## 引言
不知道大家平時的業務開發過程中 controller 層的引數校驗都是怎麼寫的？是否也存在下面這樣的直接判斷？
```java
public String add(UserVO userVO) {
if(userVO.getAge() == null){
return "年齡不能為空";
}
if(userVO.getAge() > 120){
return "年齡不能超過120";
}
if(userVO.getName().isEmpty()){
return "使用者名稱不能為空";
}
// 省略一堆引數校驗...
return "OK";
}
```
業務程式碼還沒開始寫呢，光引數校驗就寫了一堆判斷。這樣寫雖然沒什麼錯，但是給人的感覺就是：不優雅，不專業。
其實`Spring`框架已經給我們封裝了一套校驗元件：validation。其特點是簡單易用，自由度高。接下來課代表使用`springboot-2.3.1.RELEASE`搭建一個簡單的 Web 工程，給大家一步一步講解在開發過程中如何優雅地做引數校驗。
## 1. 環境搭建
從`springboot-2.3`開始，校驗包被獨立成了一個`starter`元件，所以需要引入如下依賴：
```java
org.springframework.boot
org.springframework.boot
spring-boot-starter-web
```
而`springboot-2.3`之前的版本只需要引入 web 依賴就可以了。
## 2.小試牛刀
引數校驗非常簡單，首先在待校驗欄位上增加校驗規則註解
```java
public class UserVO {
@NotNull(message = "age 不能為空")
private Integer age;
}
```
然後在`controller`方法中新增`@Validated`和用於接收錯誤資訊的`BindingResult`就可以了，於是有了第一版：
```java
public String add1(@Validated UserVO userVO, BindingResult result) {
List fieldErrors = result.getFieldErrors();
if(!fieldErrors.isEmpty()){
return fieldErrors.get(0).getDefaultMessage();
}
return "OK";
}
```
通過工具(postman)去請求介面，如果引數不符合規則，會將相應的 `message`資訊返回：
```json
age 不能為空
```
內建的校驗註解有很多，羅列如下：
| 註解 | 校驗功能 |
| ---------------- | ---------------------------------- |
| @AssertFalse | 必須是false |
| @AssertTrue | 必須是true |
| @DecimalMax | 小於等於給定的值 |
| @DecimalMin | 大於等於給定的值 |
| @Digits | 可設定最大整數位數和最大小數位數 |
| @Email | 校驗是否符合Email格式 |
| @Future | 必須是將來的時間 |
| @FutureOrPresent | 當前或將來時間 |
| @Max | 最大值 |
| @Min | 最小值 |
| @Negative | 負數（不包括0） |
| @NegativeOrZero | 負數或0 |
| @NotBlank | 不為null並且包含至少一個非空白字元 |
| @NotEmpty | 不為null並且不為空 |
| @NotNull | 不為null |
| @Null | 為null |
| @Past | 必須是過去的時間 |
| @PastOrPresent | 必須是過去的時間，包含現在 |
| @PositiveOrZero | 正數或0 |
| @Size | 校驗容器的元素個數 |
## 3. 規範返回值
待校驗引數多了之後我們希望一次返回所有校驗失敗資訊，方便介面呼叫方進行調整，這就需要統一返回格式，常見的就是封裝一個結果類。
```java
public class ResultInfo{
private Integer status;
private String message;
private T response;
// 省略其他程式碼...
}
```
改造一下`controller` 方法，第二版：
```java
public ResultInfo add2(@Validated UserVO userVO, BindingResult result) {
List fieldErrors = result.getFieldErrors();
List collect = fieldErrors.stream()
.map(o -> o.getDefaultMessage())
.collect(Collectors.toList());
return new ResultInfo<>().success(400,"請求引數錯誤",collect);
}
```
請求該方法時，所有的錯誤引數就都返回了：
```json
{
"status": 400,
"message": "請求引數錯誤",
"response": [
"年齡必須在[1,120]之間",
"bg 欄位的整數位最多為3位，小數位最多為1位",
"name 不能為空",
"email 格式錯誤"
]
}
```
## 4. 全域性異常處理
每個`Controller`方法中都如果都寫一遍對`BindingResult`資訊的處理，使用起來還是很繁瑣。可以通過全域性異常處理的方式統一處理校驗異常。
當我們寫了`@validated`註解，不寫`BindingResult`的時候，Spring 就會丟擲異常。由此，可以寫一個全域性異常處理類來統一處理這種校驗異常，從而免去重複組織異常資訊的程式碼。
全域性異常處理類只需要在類上標註`@RestControllerAdvice`，並在處理相應異常的方法上使用`@ExceptionHandler`註解，寫明處理哪個異常即可。
```java
@RestControllerAdvice
public class GlobalControllerAdvice {
private static final String BAD_REQUEST_MSG = "客戶端請求引數錯誤";
// <1> 處理 form data方式呼叫介面校驗失敗丟擲的異常
@ExceptionHandler(BindException.class)
public ResultInfo bindExceptionHandler(BindException e) {
List fieldErrors = e.getBindingResult().getFieldErrors();
List collect = fieldErrors.stream()
.map(o -> o.getDefaultMessage())
.collect(Collectors.toList());
return new ResultInfo().success(HttpStatus.BAD_REQUEST.value(), BAD_REQUEST_MSG, collect);
}
// <2> 處理 json 請求體呼叫介面校驗失敗丟擲的異常
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResultInfo methodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) {
List fieldErrors = e.getBindingResult().getFieldErrors();
List collect = fieldErrors.stream()
.map(o -> o.getDefaultMessage())
.collect(Collectors.toList());
return new ResultInfo().success(HttpStatus.BAD_REQUEST.value(), BAD_REQUEST_MSG, collect);
}
// <3> 處理單個引數校驗失敗丟擲的異常
@ExceptionHandler(ConstraintViolationException.class)
public ResultInfo constraintViolationExceptionHandler(ConstraintViolationException e) {
Set> constraintViolations = e.getConstraintViolations();
List collect = constraintViolations.stream()
.map(o -> o.getMessage())
.collect(Collectors.toList());
return new ResultInfo().success(HttpStatus.BAD_REQUEST.value(), BAD_REQUEST_MSG, collect);
}
}
```
事實上，在全域性異常處理類中，我們可以寫多個異常處理方法，課代表總結了三種引數校驗時可能引發的異常：
1. 使用form data方式呼叫介面，校驗異常丟擲 BindException
2. 使用 json 請求體呼叫介面，校驗異常丟擲 MethodArgumentNotValidException
3. 單個引數校驗異常丟擲ConstraintViolationException
> 注：單個引數校驗需要在引數上增加校驗註解，並在類上標註`@Validated`。
全域性異常處理類可以新增各種需要處理的異常，比如新增一個對`Exception.class`的異常處理，當所有`ExceptionHandler`都無法處理時，由其記錄異常資訊，並返回友好提示。
## 5.分組校驗
如果同一個引數，需要在不同場景下應用不同的校驗規則，就需要用到分組校驗了。比如：新註冊使用者還沒起名字，我們允許`name`欄位為空，但是不允許將名字更新為空字元。
分組校驗有三個步驟：
1. 定義一個分組類（或介面）
2. 在校驗註解上新增`groups`屬性指定分組
3. `Controller`方法的`@Validated`註解新增分組類
```java
public interface Update extends Default{
}
```
```java
public class UserVO {
@NotBlank(message = "name 不能為空",groups = Update.class)
private String name;
// 省略其他程式碼...
}
```
```java
@PostMapping("update")
public ResultInfo update(@Validated({Update.class}) UserVO userVO) {
return new ResultInfo().success(userVO);
}
```
細心的同學可能已經注意到，自定義的`Update`分組介面繼承了`Default`介面。校驗註解(如：` @NotBlank`)和`@validated`預設都屬於`Default.class`分組，這一點在`javax.validation.groups.Default`註釋中有說明
```java
/**
* Default Jakarta Bean Validation group.
* {
@Override
public boolean isValid(String value, ConstraintValidatorContext context) {
// null 不做檢驗
if (value == null) {
return true;
}
if (value.contains(" ")) {
// 校驗失敗
return false;
}
// 校驗成功
return true;
}
}
```
自定義校驗註解使用起來和內建註解無異，在需要的欄位上新增相應註解即可，同學們可以自行驗證
## 回顧
以上就是如何使用 Spring Validation 優雅地校驗引數的全部內容，下面重點總結一下文中提到的校驗特性
1. 內建多種常用校驗註解
2. 支援單個引數校驗
3. 結合全域性異常處理自動組裝校驗異常
4. 分組校驗
5. 支援遞迴校驗
6. 自定義校驗
本文程式碼已上傳至
[GitHub](https://github.com/zhengxl5566/springboot-demo)
---
* Unless a list of groups is explicitly defined: *
-
*
- constraints belong to the {@code Default} group
- validation applies to the {@code Default} group *