SpringBoot引數校驗Validator框架詳解

2022-06-15 18:01:21

SpringBoot 如何進行引數校驗

在日常的介面開發中，為了防止非法引數對業務造成影響，經常需要對介面的引數做校驗，例如登入的時候需要校驗使用者名稱密碼是否為空，建立使用者的時候需要校驗郵件、手機號碼格式是否準確。靠程式碼對介面引數一個個校驗的話就太繁瑣了，程式碼可讀性極差。

Validator框架就是為了解決開發人員在開發的時候少寫程式碼，提升開發效率；Validator專門用來進行介面引數校驗，例如常見的必填校驗，email格式校驗，使用者名稱必須位於6到12之間等等…

Validator校驗框架遵循了JSR-303驗證規範（引數校驗規範）, JSR是Java Specification Requests的縮寫。

1.整合Validator校驗框架

1.1. 引入依賴包

<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 依賴就可以了。

註解	功能
@AssertFalse	可以為null,如果不為null的話必須為false
@AssertTrue	可以為null,如果不為null的話必須為true
@DecimalMax	設定不能超過最大值
@DecimalMin	設定不能超過最小值
@Digits	設定必須是數位且數位整數的位數和小數的位數必須在指定範圍內
@Future	日期必須在當前日期的未來
@Past	日期必須在當前日期的過去
@Max	最大不得超過此最大值
@Min	最大不得小於此最小值
@NotNull	不能為null，可以是空
@Null	必須為null
@Pattern	必須滿足指定的正規表示式
@Size	集合、陣列、map等的size()值必須在指定範圍內
@Email	必須是email格式
@Length	長度必須在指定範圍內
@NotBlank	字串不能為null,字串trim()後也不能等於“”
@NotEmpty	不能為null，集合、陣列、map等size()不能為0；字串trim()後可以等於“”
@Range	值必須在指定範圍內
@URL	必須是一個URL

注：此表格只是簡單的對註解功能的說明，並沒有對每一個註解的屬性進行說明；可詳見原始碼。

1.2. 定義要引數校驗的實體類

@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屬性。

1.3. 定義校驗類進行測試

@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註解，否則不生效。

1.4. 測試結果1

test1的測試結果

傳送值

POST http://localhost:8080/valid/test1
Content-Type: application/json

{
  "id": 1,
  "level": "12",
  "email": "47693899",
  "appId": "ab1c"
}

返回值

提示的是org.springframework.web.bind.MethodArgumentNotValidException異常

{
  "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的測試結果

傳送值

POST http://localhost:8080/valid/test2
Content-Type: application/x-www-form-urlencoded
id=1&level=12&email=476938977&appId=ab1c

返回值

提示的是org.springframework.validation.BindException異常

{
  "status": 500,
  "message": "org.springframework.validation.BeanPropertyBindingResult: 3 errorsnField 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的測試結果

傳送值

POST http://localhost:8080/valid/test3
Content-Type: application/x-www-form-urlencoded

email=476938977

返回值

提示的是javax.validation.ConstraintViolationException異常

{
  "status": 500,
  "message": "test3.email: 不是一個合法的電子郵件地址",
  "data": null,
  "timestamp": 1628239281022
}

1.5. 問題

雖然我們之前定義了全域性異常攔截器，也看到了攔截器確實生效了，但是Validator校驗框架返回的錯誤提示太臃腫了，不便於閱讀，為了方便前端提示，我們需要將其簡化一下。

通過將引數異常加入全域性異常來解決

1.6. 將引數異常加入全域性異常

直接修改之前定義的RestExceptionHandler，單獨攔截引數校驗的三個異常：

javax.validation.ConstraintViolationException，

org.springframework.validation.BindException，

org.springframework.web.bind.MethodArgumentNotValidException，

@Slf4j
@RestControllerAdvice
public class RestExceptionHandler {
    /**
     * 預設全域性例外處理。
     * @param e the e
     * @return ResultData
     */
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ResultData<String> exception(Exception e) {
        log.error("全域性異常資訊 ex={}", e.getMessage(), e);
        return ResultData.fail(ReturnCode.RC500.getCode(),e.getMessage());
    }
    
    @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);
    }
    
}

1.7. 測試結果2

test1測試結果

傳送值

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
}

2. 自定義註解

雖然Spring Validation 提供的註解基本上夠用，但是面對複雜的定義，我們還是需要自己定義相關注解來實現自動校驗。

比如上面實體類中的sex性別屬性，只允許前端傳遞傳 M，F 這2個列舉值，如何實現呢？

2.1. 第一步，建立自定義註解

@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();
    }
}

可以根據Validator框架定義好的註解來仿寫，基本上一致

2.2. 第二步，自定義校驗邏輯

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);
    }
}

2.3. 第三步，在欄位上增加註解

@ApiModelProperty(value = "性別")
@EnumString(value = {"F","M"}, message="性別只允許為F或M")
private String sex;

2.4. 第四步，體驗效果

POST http://localhost:8080/valid/test2
Content-Type: application/x-www-form-urlencoded
id=1&name=javadaily&level=12&email=476938977@qq.com&appId=ab1cdddd&sex=N

{
  "status": 400,
  "message": "性別只允許為F或M",
  "data": null,
  "timestamp": 1628435243723
}

3. 分組校驗

一個VO物件在新增的時候某些欄位為必填，在更新的時候又非必填。如上面的ValidVO中 id 和 appId 屬性在新增操作時都是非必填，而在編輯操作時都為必填，name在新增操作時為必填，面對這種場景你會怎麼處理呢？

在實際開發中我見到很多同學都是建立兩個VO物件，ValidCreateVO，ValidEditVO來處理這種場景，這樣確實也能實現效果，但是會造成類膨脹。

其實Validator校驗框架已經考慮到了這種場景並且提供瞭解決方案，就是分組校驗，只不過很多同學不知道而已。

要使用分組校驗，只需要三個步驟

3.1. 第一步，定義分組介面

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。

3.2. 第二步，在模型中給引數分配分組

@Data
public class ValidVO {
    @Null(groups = ValidGroup.Crud.Create.class)
    @NotNull(groups = ValidGroup.Crud.Update.class, message = "應用ID不能為空")
    private String id;

    @Length(min = 6,max = 12,message = "appId長度必須位於6到12之間")
    @Null(groups = ValidGroup.Crud.Create.class)
    @NotNull(groups = ValidGroup.Crud.Update.class, message = "應用ID不能為空")
    private String appId;

    @NotBlank(message = "名字為必填項")
    @NotBlank(groups = ValidGroup.Crud.Create.class,message = "名字為必填項")
    private String name;

    @Email(message = "請填寫正確的郵箱地址")
    private String email;

    @EnumString(value = {"F","M"}, message="性別只允許為F或M")
    private String sex;

    @NotEmpty(message = "級別不能為空")
    private String level;
}

給引數指定分組，對於未指定分組的則使用的是預設分組。

3.3. 第三步，給需要引數校驗的方法指定分組

    @PostMapping(value = "/valid/add")
    public String add(@Validated(value = ValidGroup.Crud.Create.class) ValidVO validVO){
        log.info("validEntity is {}", validVO);
        return "test3 valid success";
    }

    @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分組

3.4. 測試

POST http://localhost:8080/valid/add
Content-Type: application/x-www-form-urlencoded

name=javadaily&level=12&email=476938977@qq.com&sex=F

Create操作

在Create時我們沒有傳遞id和appId引數，校驗通過。

{
	"status": 100,
	"message": "操作成功",
	"data": "test3 valid success",
	"timestamp": 1652186105359
}

update操作

使用同樣的引數呼叫update方法時則提示引數校驗錯誤

{
	"status": 400,
	"message": "ID不能為空; 應用ID不能為空",
	"data": null,
	"timestamp": 1652186962377
}

預設校驗生效操作

由於email屬於預設分組，而我們的分組介面ValidGroup已經繼承了Default分組，所以也是可以對email欄位作引數校驗的。

故意寫錯email格式

POST http://localhost:8080/valid/add
Content-Type: application/x-www-form-urlencoded

/valid/update?name=javadaily&level=12&email=476938977&sex=F

{
	"status": 400,
	"message": "請填寫正確的郵箱地址; ID不能為空; 應用ID不能為空",
	"data": null,
	"timestamp": 1652187273865
}

4. 業務規則校驗

https://www.jb51.net/article/235644.htm

業務規則校驗指介面需要滿足某些特定的業務規則，舉個例子：業務系統的使用者需要保證其唯一性，使用者屬性不能與其他使用者產生衝突，不允許與資料庫中任何已有使用者的使用者名稱稱、手機號碼、郵箱產生重複。

這就要求在建立使用者時需要校驗使用者名稱稱、手機號碼、郵箱是否被註冊；編輯使用者時不能將資訊修改成已有使用者的屬性。

最優雅的實現方法應該是參考 Bean Validation 的標準方式，藉助自定義校驗註解完成業務規則校驗。

4.1. 自定義註解

首先我們需要建立兩個自定義註解，用於業務規則校驗：

UniqueUser:表示一個使用者是唯一的，唯一性包含：使用者名稱，手機號碼、郵箱

@Documented
@Retention(RUNTIME)
@Target({FIELD, METHOD, PARAMETER, TYPE})
@Constraint(validatedBy = UserValidation.UniqueUserValidator.class)
public @interface UniqueUser {

    String message() default "使用者名稱、手機號碼、郵箱不允許與現存使用者重複";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};
}

NotConflictUser:表示一個使用者的資訊是無衝突的，無衝突是指該使用者的敏感資訊與其他使用者不重合

@Documented
@Retention(RUNTIME)
@Target({FIELD, METHOD, PARAMETER, TYPE})
@Constraint(validatedBy = UserValidation.NotConflictUserValidator.class)
public @interface NotConflictUser {
    String message() default "使用者名稱稱、郵箱、手機號碼與現存使用者產生重複";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};
}

4.2. 實現業務校驗規則

想讓自定義驗證註解生效，需要實現 ConstraintValidator 介面。

介面的第一個引數是 自定義註解型別，第二個引數是 被註解欄位的類，因為需要校驗多個引數，我們直接傳入使用者物件。需要提到的一點是 ConstraintValidator 介面的實現類無需新增 @Component 它在啟動的時候就已經被載入到容器中了。

@Slf4j
public class UserValidation<T extends Annotation> implements ConstraintValidator<T, User> {

    protected Predicate<User> predicate = c -> true;

    @Resource
    protected UserRepository userRepository;

    @Override
    public boolean isValid(User user, ConstraintValidatorContext constraintValidatorContext) {
        return userRepository == null || predicate.test(user);
    }

    /**
     * 校驗使用者是否唯一
     * 即判斷資料庫是否存在當前新使用者的資訊，如使用者名稱，手機，郵箱
     */
    public static class UniqueUserValidator extends UserValidation<UniqueUser>{
        @Override
        public void initialize(UniqueUser uniqueUser) {
            predicate = c -> !userRepository.existsByUserNameOrEmailOrTelphone(c.getUserName(),c.getEmail(),c.getTelphone());
        }
    }

    /**
     * 校驗是否與其他使用者衝突
     * 將使用者名稱、郵件、電話改成與現有完全不重複的，或者只與自己重複的，就不算衝突
     */
    public static class NotConflictUserValidator extends UserValidation<NotConflictUser>{
        @Override
        public void initialize(NotConflictUser notConflictUser) {
            predicate = c -> {
                log.info("user detail is {}",c);
                Collection<User> collection = userRepository.findByUserNameOrEmailOrTelphone(c.getUserName(), c.getEmail(), c.getTelphone());
                // 將使用者名稱、郵件、電話改成與現有完全不重複的，或者只與自己重複的，就不算衝突
                return collection.isEmpty() || (collection.size() == 1 && collection.iterator().next().getId().equals(c.getId()));
            };
        }
    }

}

這裡使用Predicate函數式介面對業務規則進行判斷。

4.3. 測試程式碼

@RestController
@RequestMapping("/senior/user")
@Slf4j
@Validated
public class UserController {
    @Autowired
    private UserRepository userRepository;
    

    @PostMapping
    public User createUser(@UniqueUser @Valid User user){
        User savedUser = userRepository.save(user);
        log.info("save user id is {}",savedUser.getId());
        return savedUser;
    }

    @SneakyThrows
    @PutMapping
    public User updateUser(@NotConflictUser @Valid @RequestBody User user){
        User editUser = userRepository.save(user);
        log.info("update user is {}",editUser);
        return editUser;
    }
}

使用很簡單，只需要在方法上加入自定義註解即可，業務邏輯中不需要新增任何業務規則的程式碼。

POST http://localhost:8080/valid/add
Content-Type: application/json

/senior/user

{
    "userName" : "100001"
}

{
	"status": 400,
	"message": "使用者名稱、手機號碼、郵箱不允許與現存使用者重複",
	"data": null,
	"timestamp": 1652196524725
}

總結

通過上面幾步操作，業務校驗便和業務邏輯就完全分離開來，在需要校驗時用@Validated註解自動觸發，或者通過程式碼手動觸發執行，可根據你們專案的要求，將這些註解應用於控制器、服務層、持久層等任何層次的程式碼之中。

這種方式比任何業務規則校驗的方法都優雅，推薦大家在專案中使用。在開發時可以將不帶業務含義的格式校驗註解放到 Bean 的類定義之上，將帶業務邏輯的校驗放到 Bean 的類定義的外面。這兩者的區別是放在類定義中的註解能夠自動執行，而放到類外面則需要像前面程式碼那樣，明確標出註解時才會執行。

到此這篇關於SpringBoot引數校驗Validator框架的文章就介紹到這了,更多相關SpringBoot引數校驗內容請搜尋it145.com以前的文章或繼續瀏覽下面的相關文章希望大家以後多多支援it145.com！

SpringBoot引數校驗Validator框架詳解

目錄

SpringBoot 如何進行引數校驗

1.整合Validator校驗框架

1.1. 引入依賴包

1.2. 定義要引數校驗的實體類

1.3. 定義校驗類進行測試

1.4. 測試結果1

1.5. 問題

1.6. 將引數異常加入全域性異常

1.7. 測試結果2

2. 自定義註解

2.1. 第一步，建立自定義註解

2.2. 第二步，自定義校驗邏輯

2.3. 第三步，在欄位上增加註解

2.4. 第四步，體驗效果

3. 分組校驗

3.1. 第一步，定義分組介面

3.2. 第二步，在模型中給引數分配分組

3.3. 第三步，給需要引數校驗的方法指定分組

3.4. 測試

4. 業務規則校驗

4.1. 自定義註解

4.2. 實現業務校驗規則

4.3. 測試程式碼

總結

熱門文章