SpringBoot參數校驗最全使用

引入maven依賴（可選）

如果我們的項目使用了Spring Boot，hibernate validator框架已經集成在 spring-boot-starter-web中，所以無需再添加其他依賴。如果不是Spring Boot項目，則需要添加如下依賴：

<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.0.8.Final</version>
</dependency>

 

常用注解介紹

注解	作用類型	來源	說明
@Null	任何類型		屬性必須為null
@NotNull	任何類型		屬性不能為null
@NotEmpty	集合	hibernate validator擴展注解	集合不能為null，且size大於0
@NotBlank	字符串、字符	hibernate validator擴展注解	字符類不能為null，且去掉空格之后長度大於0
@AssertTrue	Boolean、boolean		布爾屬性必須是true
@Min	數字類型（原子和包裝）		限定數字的最小值（整型）
@Max	同@Min		限定數字的最大值（整型）
@DecimalMin	同@Min		限定數字的最小值（字符串，可以是小數）
@DecimalMax	同@Min		限定數字的最大值（字符串，可以是小數）
@Range	數字類型（原子和包裝）	hibernate validator擴展注解	限定數字范圍（長整型）
@Length(min=,max=)	字符串	hibernate validator擴展注解	限定字符串長度
@Size	集合		限定集合大小
@Past	時間、日期		必須是一個過去的時間或日期
@Future	時期、時間		必須是一個未來的時間或日期
@Email	字符串	hibernate validator擴展注解	必須是一個郵箱格式
@Pattern	字符串、字符		正則匹配字符串

 

單參數校驗

controller類上必須添加@Validated注解，如下所示：

 

@RestController
@RequestMapping("/user")
@Validated // 需要添加的注解
public class UserController {
  // do something
}

 

方法參數前面加上注解即可， 如下所示：

public Result deleteUser(@NotNull(message = "id不能為空") Long id) {
  // do something
}

 

對象參數校驗

對象參數校驗使用時，需要先在對象的校驗屬性上添加注解，然后在Controller方法的對象參數前添加@Validated注解，如下所示：

public Result addUser(@RequestBody @Validated UserDto userDto) {
    // do something
}

public class UserDto {
  @NotBlank(message="名稱不能為空")
  private String name;

  @NotNull(message="年齡不能為空")
  private Integer age;
  
  ……
}

 

嵌套對象校驗

如果需要校驗的參數對象中還嵌套有一個對象屬性，而該嵌套的對象屬性也需要校驗，那么就需要在該對象屬性上增加@Valid注解。

public class UserDto {
    @NotNull
    private Long id;
    
    @NotBlank
    private String name;

    @NotNull
    private Integer age;
    
    @Valid
    private Phone phone;
    
    ……
}

public class Phone {
    @NotBlank
    private String type;
    
    @NotBlank
    private String phoneNum;
}

 

分組校驗

在對象參數校驗場景下，有一種特殊場景，同一個參數對象在不同的場景下有不同的校驗規則。比如，在創建對象時不需要傳入id字段（id字段是主鍵，由系統生成，不由用戶指定），但是在修改對象時就必須要傳入id字段。在這樣的場景下就需要對注解進行分組。

1）組件默認有個分組Default.class, 所以我們可以再創建一個分組例如UpdateAction.class，如下所示：

public interface UpdateAction {
}

2）在參數類中需要校驗的屬性上，在注解中添加groups屬性（表示Default.class默認情況下會校驗name,age參數，而在UpdateAction.class情況下會校驗id參數），如下所示：

public class UserDto {
    @NotNull(groups = {UpdateAction.class}, message = "id不能為空")
    private Long id;
    
    @NotBlank
    private String name;

    @NotNull
    private Integer age;
    
    ……
}

 3）在controller的方法中，在@Validated注解里指定哪種場景即可（沒有指定就代表采用Default.class，采用其他分組則需要顯示指定）。如下代碼便表示在addUser()接口中按照默認情況進行參數校驗，在updateUser()接口中按照默認情況和UpdateAction分組對參數進行共同校驗。

public Result addUser(@Validated UserDto userDto) {
  // do something
}

public Result updateUser(@Validated({Default.class, UpdateAction.class}) UserDto userDto) {
  // do something
}

 

枚舉校驗

枚舉校驗hibernate validator並不支持。需要自己擴展實現。

1） 定義EnumChck注解，如下所示：

@Documented
@Constraint(validatedBy = EnumConstraintValidator.class)
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
@Retention(RUNTIME)
@Repeatable(EnumCheck.List.class)
public @interface EnumCheck {
    String message() default "{javax.validation.constraints.EnumCheck.message}";

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

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

    /**
     * 枚舉類
     *
     */
    Class<? extends EnumValidator> clazz();

    /**
     * 調用的方法名稱
     */
    String method() default "getValue";

    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
    @Retention(RUNTIME)
    @Documented
    @interface List {
        EnumCheck[] value();
    }
}

2） 定義EnumValidator接口，讓需要校驗的枚舉類實現其接口的getValue()方法，如下所示：

public interface EnumValidator {
    Object getValue();
}

3）自定義實現EnumConstraintValidator，需要實現ConstraintValidator接口，如下所示：

public class EnumConstraintValidator implements ConstraintValidator<EnumCheck, Object> {
    /**
     * 注解對象
     */
    private EnumCheck annotation;

    /**
     * 初始化方法
     *
     * @param constraintAnnotation 注解對象
     */
    @Override
    public void initialize(EnumCheck constraintAnnotation) {
        this.annotation = constraintAnnotation;
    }

    @Override
    public boolean isValid(Object value, ConstraintValidatorContext context) {
        if (Objects.isNull(value)) {
            return false;
        }

        Object[] enumConstants = annotation.clazz().getEnumConstants();
        try {
            Method method = annotation.clazz().getMethod(annotation.method());
            for (Object enumConstant : enumConstants) {
                if (value.equals(method.invoke(enumConstant))) {
                    return true;
                }
            }
        } catch (NoSuchMethodException | IllegalAccessException | InvocationTargetException e) {
            throw new RuntimeException(e);
        }

        return false;
    }
}

4） 具體使用步驟如下：

具體枚舉類實現上面定義的EnumValidator接口：

public enum RefNodeType implements EnumValidator {
    PROJECT("project", "項目"),
    FIELD("field", "變量"),
    FUNC("func", "函數");

    private final String code;
    private final String label;

    RefNodeType(String code, String label) {
        this.code = code;
        this.label = label;
    }

    public String getCode() {
        return code;
    }

    public String getLabel() {
        return label;
    }

    @Override // 需要實現getValue方法
    public Object getValue() {
        return code;
    }
}

參數校驗加上@EnumCheck枚舉校驗注解，如下所示：

public class TestDto {
  @NotBlank(message = "變量類型不能為空")
  @EnumCheck(clazz = RefNodeType.class, message = "變量類型不合法") // 加上枚舉校驗注解
  private String sourceType;
}

 

正則通用校驗

1）定義RegRule接口，將需要用到的正則表達式定義為接口屬性，如下所示：

public interface RegRule {
    String MOBILE = "^(((13[0-9])|(14[579])|(15([0-3]|[5-9]))|(16[6])|(17[0135678])|(18[0-9])|(19[89]))\\d{8})$";
}

2）對象屬性加上@Pattern注解，如下所示：

public class UserDto {
  @Pattern(regexp = RegRule.MOBILE, message = "手機號格式不正確")
  private String mobile;
}

 

 各類異常捕獲處理

參數校驗失敗后會拋出異常，我們只需要在全局異常處理類中捕獲參數校驗的失敗異常，然后將錯誤消息添加到返回值中即可。捕獲異常的方法如下所示，返回值Result是我們系統自定義的返回值類。

@RestControllerAdvice
public class GlobalExceptionHandler {
     /**
      * 全局異常處理
      */
     @ExceptionHandler(Exception.class)
     public Result handleException(Exception ex, HttpServletRequest request, HttpServletResponse response) {
         // do something
     }
}

1）缺少參數拋出的異常是MissingServletRequestParameterException，如下所示：

if (e instanceof MissingServletRequestParameterException){
    Result result = Result.buildErrorResult(ErrorCodeEnum.PARAM_ILLEGAL);
    String msg = MessageFormat.format("缺少參數{0}", ((MissingServletRequestParameterException) e).getParameterName());
    result.setMessage(msg);
    return result;
}

2）單參數校驗失敗后拋出的異常是ConstraintViolationException，如下所示：

if (e instanceof ConstraintViolationException){
  Result result = Result.buildErrorResult(ErrorCodeEnum.PARAM_ILLEGAL);
  Set<ConstraintViolation<?>> sets = ((ConstraintViolationException) e).getConstraintViolations();
  if(CollectionUtils.isNotEmpty(sets)){
    StringBuilder sb = new StringBuilder();
    sets.forEach(error -> {
                    if (error instanceof FieldError) {
                        sb.append(((FieldError)error).getField()).append(":");
                    }
                    sb.append(error.getMessage()).append(";");
                });
    String msg = sb.toString();
    msg = StringUtils.substring(msg, 0, msg.length() -1);
    result.setMessage(msg);
  }
  return result;
}

3）get請求的對象參數校驗失敗后拋出的異常是BindException，如下所示：

if (e instanceof BindException){
      Result result = Result.buildErrorResult(ErrorCodeEnum.PARAM_ILLEGAL);
      List<ObjectError> errors = ((BindException) e).getBindingResult().getAllErrors();
      String msg = getValidExceptionMsg(errors);
      if (StringUtils.isNotBlank(msg)){
        result.setMessage(msg);
      }
      
      return result;
}

private String getValidExceptionMsg(List<ObjectError> errors) {
  if(CollectionUtils.isNotEmpty(errors)){
    StringBuilder sb = new StringBuilder();
    errors.forEach(error -> {
                    if (error instanceof FieldError) {
                       sb.append(((FieldError)error).getField()).append(":");
                    }
                    sb.append(error.getDefaultMessage()).append(";");
                });
    String msg = sb.toString();
    msg = StringUtils.substring(msg, 0, msg.length() -1);
    return msg;
  }
  return null;
}

4）post請求的對象參數校驗失敗后拋出的異常是MethodArgumentNotValidException，如下所示：

if (e instanceof MethodArgumentNotValidException){
      Result result = Result.buildErrorResult(ErrorCodeEnum.PARAM_ILLEGAL);
      List<ObjectError> errors = ((MethodArgumentNotValidException) e).getBindingResult().getAllErrors();
      String msg = getValidExceptionMsg(errors);
      if (StringUtils.isNotBlank(msg)){
        result.setMessage(msg);
      }
      
      return result;
}