在日常的接口開發中，為了防止非法參數對業務造成影響，經常需要對接口的參數做校驗，例如登錄的時候需要校驗用戶名密碼是否為空，創建用戶的時候需要校驗郵件、手機號碼格式是否準確。靠代碼對接口參數一個個校驗的話就太繁瑣了，代碼可讀性極差。Validator框架就是為了解決開發人員在開發的時候少寫代碼，提升開發效率；Validator專門用來進行接口參數校驗，例如常見的必填校驗，email格式校驗，用戶名必須位于6到12之間 等等…

1. 集成Validator校驗框架

1.1. 引入依賴包

<dependency>
  <groupId>org.springframework.boot<span class="hljs-name"groupId>
  <artifactId>spring-boot-starter-web<span class="hljs-name"artifactId>
<span class="hljs-name"dependency>

<dependency>
  <groupId>org.springframework.boot<span class="hljs-name"groupId>
  <artifactId>spring-boot-starter-validation<span class="hljs-name"artifactId>
<span class="hljs-name"dependency>

注：從springboot-2.3開始，校驗包被獨立成了一個starter組件，所以需要引入validation和web，而springboot-2.3之前的版本只需要引入 web 依賴就可以了。

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

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

• 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 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

1.7. 新的測試結果

• 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. 第一步，創建自定義注解

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

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

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

定義處理邏輯EnumStringValidator

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
}
復制代碼