必讀！SpringBoot接口參數(shù)校驗N種實用技巧大揭秘
環(huán)境：SpringBoot2.6.12
實際的開發(fā)工作中大部分的接口都是需要進(jìn)行參數(shù)有效性校驗的，參數(shù)可能是簡單的基本數(shù)據(jù)類型，也可能是對象類型，基本上所有接收參數(shù)的接口都是需要對這些參數(shù)進(jìn)行校驗的，你對這些參數(shù)是怎么校驗的？接下來帶你一起見識下我在實際項目中都應(yīng)用過哪些校驗姿勢！。該案例會詳細(xì)介紹如下 7 方面的內(nèi)容。
- 簡單參數(shù)校驗
- 參數(shù)校驗分組
- 單個參數(shù)校驗
- 嵌套參數(shù)校驗
- 自定義工具類參數(shù)校驗
- 國際化支持
- AOP 驗證參數(shù)統(tǒng)一處理
在正式介紹主體內(nèi)容前我們還是先要了解學(xué)習(xí)一些規(guī)范 JSR303。
JSR 是什么？
JSR 是 Java Specification Requests 的縮寫，意思是 Java 規(guī)范提案。是指向 JCP(Java Community Process)提出新增一個標(biāo)準(zhǔn)化技術(shù)規(guī)范的正式請求。任何人都可以提交 JSR，以向 Java 平臺增添新的 API 和服務(wù)。JSR 已成為 Java 界的一個重要標(biāo)準(zhǔn)。JSR-303 是 JAVA EE 6 中的一項子規(guī)范，叫做 Bean Validation，Hibernate Validator 是 Bean Validation 的參考實現(xiàn) . Hibernate Validator 提供了 JSR 303 規(guī)范中所有內(nèi)置 constraint 的實現(xiàn)，除此之外還有一些附加的 constraint。相關(guān)注解如下：
圖片
在Spring中提供了SpringValidation驗證框架對參數(shù)的驗證機(jī)制提供了@Validated（Spring'sJSR-303規(guī)范，是標(biāo)準(zhǔn)JSR-303的一個變種），javax提供了@Valid（標(biāo)準(zhǔn)JSR-303規(guī)范），結(jié)合BindingResult對象可以直接獲取錯誤信息。在本案中這兩種是等效的，但是也有區(qū)別，在接下來的案例中將會說明。
1. 配置依賴
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.aspectj</groupId>
<artifactId>aspectjrt</artifactId>
</dependency>
<dependency>
<groupId>org.aspectj</groupId>
<artifactId>aspectjweaver</artifactId>
<scope>runtime</scope>
</dependency>
</dependencies>org.aspectj 依賴是在最后我們要通過 AOP 技術(shù)來實現(xiàn)統(tǒng)一參數(shù)的校驗。
2. 參數(shù)驗證
- 簡單參數(shù)校驗
public class Users {
@NotEmpty(message = "姓名必需填寫")
private String name ;
@Min(value = 10, message = "年齡不能小于 10")
private Integer age ;
@Length(min = 6, max = 18, message = "郵箱介于 6 到 18 之間")
private String email ;
@NotEmpty(message = "電話必需填寫")
private String phone ;
// 這里的2個接口在下面的案例中會使用到
public static interface G1 {}
public static interface G2 {}
}這里對需要校驗的字段都應(yīng)用了不同的注解來約束。接下來就是在Controller接口上添加相應(yīng)的注解即可：
@ResponseBody
public class UsersController extends BaseController {
@RequestMapping(value = "/valid/save1", method = RequestMethod.POST)
public Object save1(@RequestBody @Validated Users user, BindingResult result) {
Optional<List<String>> op = valid(result) ;
if (op.isPresent()) {
return op.get() ;
}
return "success" ;
}
}
public class BaseController {
protected Optional<List<String>> valid(BindingResult result) {
if (result.hasErrors()) {
return Optional.of(result.getAllErrors().stream().map(err -> err.getDefaultMessage()).collect(Collectors.toList())) ;
}
return Optional.empty() ;
}
}接收參數(shù)的 Users 對象前面要是用@Validated 注解，并且通過 BindingResult 來收集錯誤信息（可判斷是否有錯誤信息）；測試如下：
圖片
正確情況
圖片
- 參數(shù)校驗分組
有些時候我們這一個對象可能會應(yīng)用到不同的場景，出現(xiàn)不同的校驗規(guī)則該怎么做呢？這時候我們就可以應(yīng)用分組功能，不同的應(yīng)用場景指明不同的分組即可，開始擼。注意：JSR303 是沒有分組功能的。
public class Users {
@NotEmpty(message = "姓名不能為空", groups = G1.class)
private String name ;
@Min(value = 10, message = "年齡不能小于 10", groups = G1.class)
@Min(value = 20, message = "年齡不能小于 20", groups = G2.class)
private Integer age ;
@Length(min = 6, max = 18, message = "郵箱介于 6 到 18 之間", groups = {G1.class, G2.class})
private String email ;
@NotEmpty(message = "電話必需填寫")
private String phone ;
public static interface G1 {}
public static interface G2 {}
}這里不同的字段上加了 groups 屬性，指明屬于哪個分組。注意在該實體類中我們又定義了 2 個類 G1，G2 就是為了分組用的（具體指明哪個分組）。接口處理：
@RequestMapping(value = "/valid/save1", method = RequestMethod.POST)
public Object save1(@RequestBody @Validated(Users.G1.class) Users user, BindingResult result) {
Optional<List<String>> op = valid(result) ;
if (op.isPresent()) {
return op.get() ;
}
return "success" ;
}
@RequestMapping(value = "/valid/save2", method = RequestMethod.POST)
public Object save2(@RequestBody @Validated(Users.G2.class) Users user, BindingResult result) {
Optional<List<String>> op = valid(result) ;
if (op.isPresent()) {
return op.get() ;
}
return "success" ;
}在這個兩個接口中 @Validated(Users.G2.class)分別指明了自己的分組，接下來測試看看效果。
分組 G1 測試：
圖片
從這里返回的信息來看我們的 phone 雖然寫了@NotEmpty 但是并沒有起作用，因為我們并沒有指明他的分組，并且接口上我們指明了是用 G1 分組。
分組 G2 測試：
圖片
在這個接口中發(fā)現(xiàn) name 驗證是 G1 的，所以這里不會進(jìn)行校驗，并且年齡的判斷是不能小于 20 了。
- 單個參數(shù)校驗
單個參數(shù)的校驗不需要實體對象，一般就是吧 JSR303 相關(guān)的注解直接應(yīng)用到接口參數(shù)上即可。同時還需要在 Controller 類上添加@Validated 注解。
@Validated
public class UsersController extends BaseController {
@PackMapping("/valid/find")
public Object find(@NotEmpty(message = "參數(shù) Id 不能為空") String id) {
return "查詢到參數(shù)【" + id + "】" ;
}
}該接口中直接將注解應(yīng)用到參數(shù)上。測試：
圖片
同時控制臺會輸出如下異常：
圖片
你也發(fā)現(xiàn)這種異常信息提示很不友好，接下來我們做個簡單的局部異常處理。
我們只需要在Controller添加如下方法即可：
@ExceptionHandler(ConstraintViolationException.class)
@ResponseBody
public Object ConstraintViolationExceptionHandler(ConstraintViolationException e) {
String message = e.getConstraintViolations().stream().map(ConstraintViolation::getMessage).collect(Collectors.joining());
return message ;
}在該 Controller 中我們添加了一個異常處理句柄（簡單吧將錯誤信息輸出）。
圖片
- 嵌套參數(shù)校驗
在實際的工作中往往參數(shù)對象比這復(fù)雜的多，Users 對象中可能還嵌套有其他的對象，這個其他的對象也可能需要參數(shù)的校驗。接下來我們就來看看這種嵌套參數(shù)是如何校驗的。
public class Users {
@NotEmpty(message = "姓名不能為空", groups = G1.class)
private String name ;
@Min(value = 10, message = "年齡不能小于 10", groups = G1.class)
@Min(value = 20, message = "年齡不能小于 20", groups = G2.class)
private Integer age ;
@Length(min = 6, max = 18, message = "郵箱介于 6 到 18 之間", groups = {G1.class, G2.class})
private String email ;
@NotEmpty(message = "電話必需填寫")
private String phone ;
@Valid
private Address address;
}注意：嵌套對象 Address 的校驗需要在上面加@Valid 注解。
public class Address {
@NotEmpty(message = "地址信息必需填寫")
private String addr ;
}測試接口：
@RequestMapping(value = "/valid/save3", method = RequestMethod.POST)
public Object save3(@RequestBody @Validated Users user, BindingResult result) {
Optional<List<String>> op = valid(result) ;
if (op.isPresent()) {
return op.get() ;
}
return "success" ;
}接口上沒有什么特別的與之前的一模一樣。注意：這里的校驗沒有設(shè)定分組，所以校驗時都是校驗的沒有設(shè)置分組的字段。
測試：
圖片
這里發(fā)現(xiàn)我們的地址信息根本就沒有進(jìn)行校驗。接著我們吧參數(shù)變動下
圖片
參數(shù)中我們吧 address 字段設(shè)置上后 參數(shù)進(jìn)行校驗了。接下來修改 Users 實體，吧 Address 默認(rèn) new 出來再進(jìn)行測試
@Valid
private Address address = new Address();
圖片
發(fā)現(xiàn)即便我們的入?yún)]有 address 字段也能進(jìn)行校驗了，這里大家需要注意下。
- 自定義參數(shù)校驗
請查看【技巧】API接口參數(shù)驗證的必備神器，讓你的代碼更高效！
- 國際化支持
public class Users {
@NotEmpty(message = "{name.notempty}", groups = G1.class)
private String name ;
@Min(value = 10, message = "年齡不能小于 10", groups = G1.class)
@Min(value = 20, message = "年齡不能小于 20", groups = G2.class)
private Integer age ;
@Length(min = 6, max = 18, message = "郵箱介于 6 到 18 之間", groups = {G1.class,
G2.class})
private String email ;
@NotEmpty(message = "電話必需填寫")
private String phone ;
@Valid
private Address address = new Address();
}注意這里的 name 字段中的 message 屬性我們使用了表達(dá)式的方式，而 name.notempty 為我們在資源文件中定義的 key。接下來，在 resources/下新建如下屬性文件：
圖片
屬性文件必須是 ValidationMessages 開頭。默認(rèn)文件及 zh_CN 內(nèi)容：
name.notempty=姓名必需填寫en_US 內(nèi)容：
name.notempty=name is require測試：
圖片
為了模擬英文環(huán)境，我們需要設(shè)置請求頭 Accept-Language：en-US
圖片
顯示了 en_US.properties 中定義的消息，到此國際化完成。
- AOP 驗證參數(shù)統(tǒng)一處理
自定義注解標(biāo)記需要進(jìn)行統(tǒng)一參數(shù)校驗處理的接口。
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface EnableValidate {}AOP切面類
@Component
@Aspect
public class ValidateAspect {
@Pointcut("@annotation(com.pack.params.valid.EnableValidate)")
public void valid() {}
@Before("valid()")
public void validateBefore(JoinPoint jp) {
Object[] args = jp.getArgs() ;
for (Object arg : args) {
if (arg instanceof BindingResult) {
BindingResult result = (BindingResult) arg ;
if (result.hasErrors()) {
String messages = result.getAllErrors().stream().map(err -> err.getDefaultMessage()).collect(Collectors.joining(",")) ;
throw new ParamsException(messages) ;
}
}
}
}
}定義了一個前置通知，攔截標(biāo)記有@EnableValidate 注解的接口。如果有異常信息收集錯誤信息然后拋出異常信息。測試：
@PackMapping(value = "/valid/save1", method = RequestMethod.POST)
@EnableValidate
public Object save1(@RequestBody @Validated(Users.G1.class) Users user, BindingResult result) {
Optional<List<String>> op = valid(result) ;
if (op.isPresent()) {
return op.get() ;
}
return "success" ;
}
圖片
到此我們通過 AOP 技術(shù)實現(xiàn)了參數(shù)統(tǒng)一處理，但是這樣輸出錯誤信息很不友好，接下來我們來完善下，通過全局異常通知攔截處理。這里的異常信息我們可以通過全局異常處理下格式。
完畢！！！
