java開發SpringBoot參數校驗過程示例教程
大傢好,我是飄渺。
前幾天寫瞭一篇SpringBoot如何統一後端返回格式?老鳥們都是這樣玩的!
閱讀效果還不錯,而且被很多號主都轉載過,今天我們繼續第二篇,來聊聊在SprinBoot中如何集成參數校驗Validator,以及參數校驗的高階技巧(自定義校驗,分組校驗)。
此文是依賴於前文的代碼基礎,已經在項目中加入瞭全局異常校驗器。(代碼倉庫在文末)
首先我們來看看什麼是Validator參數校驗器,為什麼需要參數校驗?
為什麼需要參數校驗
在日常的接口開發中,為瞭防止非法參數對業務造成影響,經常需要對接口的參數做校驗,例如登錄的時候需要校驗用戶名密碼是否為空,創建用戶的時候需要校驗郵件、手機號碼格式是否準確。靠代碼對接口參數一個個校驗的話就太繁瑣瞭,代碼可讀性極差。
Validator框架就是為瞭解決開發人員在開發的時候少寫代碼,提升開發效率;Validator專門用來進行接口參數校驗,例如常見的必填校驗,email格式校驗,用戶名必須位於6到12之間 等等…
Validator校驗框架遵循瞭JSR-303驗證規范(參數校驗規范),
JSR是 Java Specification Requests的縮寫。
接下來我們看看在SpringbBoot中如何集成參數校驗框架。
SpringBoot中集成參數校驗
第一步,引入依賴
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> </dependency>
註:從 springboot-2.3開始,校驗包被獨立成瞭一個 starter組件,所以需要引入validation和web
而 springboot-2.3之前的版本隻需要引入 web 依賴就可以瞭。
第二步,定義要參數校驗的實體類
@Data public class ValidVO { private String id; @Length(min = 6,max = 12,message = "appId長度必須位於6到12之間") private String appId; @NotBlank(message = "名字為必填項") private String name; @Email(message = "請填寫正確的郵箱地址") private String email; private String sex; @NotEmpty(message = "級別不能為空") private String level; }
在實際開發中對於需要校驗的字段都需要設置對應的業務提示,即message屬性。
常見的約束註解如下:
註解 | 功能 |
---|---|
@AssertFalse | 可以為null,如果不為null的話必須為false |
@AssertTrue | 可以為null,如果不為null的話必須為true |
@DecimalMax | 設置不能超過最大值 |
@DecimalMin | 設置不能超過最小值 |
@Digits | 設置必須是數字且數字整數的位數和小數的位數必須在指定范圍內 |
@Future | 日期必須在當前日期的未來 |
@Past | 日期必須在當前日期的過去 |
@Max | 最大不得超過此最大值 |
@Min | 最大不得小於此最小值 |
@NotNull | 不能為null,可以是空 |
@Null | 必須為null |
@Pattern | 必須滿足指定的正則表達式 |
@Size | 集合、數組、map等的size()值必須在指定范圍內 |
必須是email格式 | |
@Length | 長度必須在指定范圍內 |
@NotBlank | 字符串不能為null,字符串trim()後也不能等於“” |
@NotEmpty | 不能為null,集合、數組、map等size()不能為0;字符串trim()後可以等於“” |
@Range | 值必須在指定范圍內 |
@URL | 必須是一個URL |
註:此表格隻是簡單的對註解功能的說明,並沒有對每一個註解的屬性進行說明;可詳見源碼。
第三步,定義校驗類進行測試
@RestController @Slf4j @Validated public class ValidController { @ApiOperation("RequestBody校驗") @PostMapping("/valid/test1") public String test1(@Validated @RequestBody ValidVO validVO){ log.info("validEntity is {}", validVO); return "test1 valid success"; } @ApiOperation("Form校驗") @PostMapping(value = "/valid/test2") public String test2(@Validated ValidVO validVO){ log.info("validEntity is {}", validVO); return "test2 valid success"; } @ApiOperation("單參數校驗") @PostMapping(value = "/valid/test3") public String test3(@Email String email){ log.info("email is {}", email); return "email valid success"; } }
這裡我們先定義三個方法test1,test2,test3,test1使用瞭 @RequestBody
註解,用於接受前端發送的json數據,test2模擬表單提交,test3模擬單參數提交。註意,當使用單參數校驗時需要在Controller上加上@Validated註解,否則不生效。
第四步,體驗效果
調用test1方法
提示的是org.springframework.web.bind.MethodArgumentNotValidException異常
POST http://localhost:8080/valid/test1 Content-Type: application/json { "id": 1, "level": "12", "email": "47693899", "appId": "ab1c" }
{ "status": 500, "message": "Validation failed for argument [0] in public java.lang.String com.jianzh5.blog.valid.ValidController.test1(com.jianzh5.blog.valid.ValidVO) with 3 errors: [Field error in object 'validVO' on field 'email': rejected value [47693899]; codes [Email.validVO.email,Email.email,Email.java.lang.String,Email]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [validVO.email,email]; arguments []; default message [email],[Ljavax.validation.constraints.Pattern$Flag;@26139123,.*]; default message [不是一個合法的電子郵件地址]]...", "data": null, "timestamp": 1628239624332 }
調用test2方法
提示的是org.springframework.validation.BindException異常
POST http://localhost:8080/valid/test2 Content-Type: application/x-www-form-urlencoded id=1&level=12&email=476938977&appId=ab1c
{ "status": 500, "message": "org.springframework.validation.BeanPropertyBindingResult: 3 errors\nField error in object 'validVO' on field 'name': rejected value [null]; codes [NotBlank.validVO.name,NotBlank.name,NotBlank.java.lang.String,NotBlank]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [validVO.name,name]; arguments []; default message [name]]; default message [名字為必填項]...", "data": null, "timestamp": 1628239301951 }
調用test3方法,
提示的是javax.validation.ConstraintViolationException異常
POST http://localhost:8080/valid/test3 Content-Type: application/x-www-form-urlencoded email=476938977
{ "status": 500, "message": "test3.email: 不是一個合法的電子郵件地址", "data": null, "timestamp": 1628239281022 }
通過加入 Validator
校驗框架可以幫助我們自動實現參數的校驗。
參數異常加入全局異常處理器
雖然我們之前定義瞭全局異常攔截器,也看到瞭攔截器確實生效瞭,但是 Validator
校驗框架返回的錯誤提示太臃腫瞭,不便於閱讀,為瞭方便前端提示,我們需要將其簡化一下。
直接修改之前定義的 RestExceptionHandler
,單獨攔截參數校驗的三個異常:
javax.validation.ConstraintViolationException,
org.springframework.validation.BindException,
org.springframework.web.bind.MethodArgumentNotValidException,
代碼如下:
@ExceptionHandler(value = {BindException.class, ValidationException.class, MethodArgumentNotValidException.class}) public ResponseEntity<ResultData<String>> handleValidatedException(Exception e) { ResultData<String> resp = null; if (e instanceof MethodArgumentNotValidException) { // BeanValidation exception MethodArgumentNotValidException ex = (MethodArgumentNotValidException) e; resp = ResultData.fail(HttpStatus.BAD_REQUEST.value(), ex.getBindingResult().getAllErrors().stream() .map(ObjectError::getDefaultMessage) .collect(Collectors.joining("; ")) ); } else if (e instanceof ConstraintViolationException) { // BeanValidation GET simple param ConstraintViolationException ex = (ConstraintViolationException) e; resp = ResultData.fail(HttpStatus.BAD_REQUEST.value(), ex.getConstraintViolations().stream() .map(ConstraintViolation::getMessage) .collect(Collectors.joining("; ")) ); } else if (e instanceof BindException) { // BeanValidation GET object param BindException ex = (BindException) e; resp = ResultData.fail(HttpStatus.BAD_REQUEST.value(), ex.getAllErrors().stream() .map(ObjectError::getDefaultMessage) .collect(Collectors.joining("; ")) ); } return new ResponseEntity<>(resp,HttpStatus.BAD_REQUEST); }
體驗效果
POST http://localhost:8080/valid/test1 Content-Type: application/json { "id": 1, "level": "12", "email": "47693899", "appId": "ab1c" }
POST http://localhost:8080/valid/test1 Content-Type: application/json { "id": 1, "level": "12", "email": "47693899", "appId": "ab1c" }
{ "status": 400, "message": "名字為必填項; 不是一個合法的電子郵件地址; appId長度必須位於6到12之間", "data": null, "timestamp": 1628435116680 }
是不是感覺清爽多瞭?
自定義參數校驗
雖然Spring Validation 提供的註解基本上夠用,但是面對復雜的定義,我們還是需要自己定義相關註解來實現自動校驗。
比如上面實體類中的sex性別屬性,隻允許前端傳遞傳 M,F 這2個枚舉值,如何實現呢?
第一步,創建自定義註解
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE}) @Retention(RUNTIME) @Repeatable(EnumString.List.class) @Documented @Constraint(validatedBy = EnumStringValidator.class)//標明由哪個類執行校驗邏輯 public @interface EnumString { String message() default "value not in enum values."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; /** * @return date must in this value array */ String[] value(); /** * Defines several {@link EnumString} annotations on the same element. * * @see EnumString */ @Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE}) @Retention(RUNTIME) @Documented @interface List { EnumString[] value(); } }
第二步,自定義校驗邏輯
public class EnumStringValidator implements ConstraintValidator<EnumString, String> { private List<String> enumStringList; @Override public void initialize(EnumString constraintAnnotation) { enumStringList = Arrays.asList(constraintAnnotation.value()); } @Override public boolean isValid(String value, ConstraintValidatorContext context) { if(value == null){ return true; } return enumStringList.contains(value); } }
第三步,在字段上增加註解
@ApiModelProperty(value = "性別") @EnumString(value = {"F","M"}, message="性別隻允許為F或M") private String sex;
第四步,體驗效果
POST http://localhost:8080/valid/test2 Content-Type: application/x-www-form-urlencoded id=1&name=javadaily&level=12&[email protected]&appId=ab1cdddd&sex=N
{ "status": 400, "message": "性別隻允許為F或M", "data": null, "timestamp": 1628435243723 }
分組校驗
一個VO對象在新增的時候某些字段為必填,在更新的時候又非必填。如上面的 ValidVO
中 id 和 appId 屬性在新增操作時都是非必填,而在編輯操作時都為必填,name在新增操作時為必填,面對這種場景你會怎麼處理呢?
在實際開發中我見到很多同學都是建立兩個VO對象,ValidCreateVO
,ValidEditVO
來處理這種場景,這樣確實也能實現效果,但是會造成類膨脹,而且極其容易被開發老鳥們嘲笑。
其實 Validator
校驗框架已經考慮到瞭這種場景並且提供瞭解決方案,就是分組校驗,隻不過很多同學不知道而已。要使用分組校驗,隻需要三個步驟:
第一步:定義分組接口
public interface ValidGroup extends Default { interface Crud extends ValidGroup{ interface Create extends Crud{ } interface Update extends Crud{ } interface Query extends Crud{ } interface Delete extends Crud{ } } }
這裡我們定義一個分組接口ValidGroup讓其繼承 javax.validation.groups.Default
,再在分組接口中定義出多個不同的操作類型,Create,Update,Query,Delete。至於為什麼需要繼承Default我們稍後再說。
第二步,在模型中給參數分配分組
@Data @ApiModel(value = "參數校驗類") public class ValidVO { @ApiModelProperty("ID") @Null(groups = ValidGroup.Crud.Create.class) @NotNull(groups = ValidGroup.Crud.Update.class, message = "應用ID不能為空") private String id; @Null(groups = ValidGroup.Crud.Create.class) @NotNull(groups = ValidGroup.Crud.Update.class, message = "應用ID不能為空") @ApiModelProperty(value = "應用ID",example = "cloud") private String appId; @ApiModelProperty(value = "名字") @NotBlank(groups = ValidGroup.Crud.Create.class,message = "名字為必填項") private String name; @ApiModelProperty(value = "郵箱") @Email(message = "請填寫正取的郵箱地址") privte String email; ... }
給參數指定分組,對於未指定分組的則使用的是默認分組。
第三步,給需要參數校驗的方法指定分組
@RestController @Api("參數校驗") @Slf4j @Validated public class ValidController { @ApiOperation("新增") @PostMapping(value = "/valid/add") public String add(@Validated(value = ValidGroup.Crud.Create.class) ValidVO validVO){ log.info("validEntity is {}", validVO); return "test3 valid success"; } @ApiOperation("更新") @PostMapping(value = "/valid/update") public String update(@Validated(value = ValidGroup.Crud.Update.class) ValidVO validVO){ log.info("validEntity is {}", validVO); return "test4 valid success"; } }
這裡我們通過 value
屬性給 add()
和 update()
方法分別指定Create和Update分組。
第四步,體驗效果
POST http://localhost:8080/valid/add Content-Type: application/x-www-form-urlencoded name=javadaily&level=12&[email protected]&sex=F
在Create時我們沒有傳遞id和appId參數,校驗通過。
當我們使用同樣的參數調用update方法時則提示參數校驗錯誤。
{ "status": 400, "message": "ID不能為空; 應用ID不能為空", "data": null, "timestamp": 1628492514313 }
由於email屬於默認分組,而我們的分組接口 ValidGroup
已經繼承瞭 Default
分組,所以也是可以對email字段作參數校驗的。如:
POST http://localhost:8080/valid/add Content-Type: application/x-www-form-urlencoded name=javadaily&level=12&email=476938977&sex=F
{ "status": 400, "message": "請填寫正取的郵箱地址", "data": null, "timestamp": 1628492637305 }
當然如果你的ValidGroup沒有繼承Default分組,那在代碼屬性上就需要加上
@Validated(value = {ValidGroup.Crud.Create.class, Default.class}
才能讓 email
字段的校驗生效。
小結
參數校驗在實際開發中使用頻率非常高,但是很多同學還隻是停留在簡單的使用上,像分組校驗,自定義參數校驗這2個高階技巧基本沒怎麼用過,經常出現譬如建立多個VO用於接受Create,Update場景的情況,很容易被老鳥被所鄙視嘲笑,希望大傢好好掌握。
github地址:https://github.com/jianzh5/cloud-blog/
以上就是SpringBoot參數校驗過程示例教程的詳細內容,更多關於SpringBoot參數校驗的資料請關註WalkonNet其它相關文章!
推薦閱讀:
- SpringBoot參數校驗Validator框架詳解
- java集成開發SpringBoot生成接口文檔示例實現
- Spring 使用Validation 驗證框架的問題詳解
- SpringBoot 中使用 Validation 校驗參數的方法詳解
- 淺談自定義校驗註解ConstraintValidator