SpringBoot參數校驗Validator框架詳解

Posted on by

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

發送值

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 protected]&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 protected]&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參數校驗內容請搜索WalkonNet以前的文章或繼續瀏覽下面的相關文章希望大傢以後多多支持WalkonNet！

推薦閱讀：