如何在專案中優雅的校驗引數

本文看點

前言

驗證資料是貫穿所有應用程式層(從表示層到持久層)的常見任務，通常在每一層實作相同的驗證邏輯，這既費時又容易出錯，為了避免重復這些驗證，開發人員經常將驗證邏輯直接捆綁到域模型中，將域類與驗證代碼混在一起，這些驗證代碼實際上是關于類本身的元資料，與業務邏輯不相關，

JSR 380——Bean Validation2.0——定義了用于物體和方法驗證的元資料模型和API，將資料校驗邏輯通過注解的形式封裝在物體物件中，

1.關于JSR

JSR是Java Specification Requests的縮寫，意思是Java 規范提案，是指向JCP(Java Community Process)提出新增一個標準化技術規范的正式請求，任何人都可以提交JSR，以向Java平臺增添新的API和服務，JSR已成為Java界的一個重要標準，

JSR-303 是JAVA EE 6 中的一項子規范，后來的版本是Bean Validation 1.1（JSR-349），目前最新版本是Bean Validation 2.0（JSR-380），Hibernate Validator 是 Bean Validation 的參考實作 ，除了Jakarta Bean驗證API定義的約束之外，Hibernate Validator還有一些附加的 constraint；并且spring-boot-starter-web默認集成了Hibernate Validator，（springboot2.3版本已經移除hibernate-validator的依賴，需要手動引入）

2.為什么使用Hibernate Validator

• 提高代碼整潔度;
• 驗證邏輯與業務邏輯之間進行了分離，降低了程式耦合度；
• 統一且規范的驗證方式，無需你再次撰寫重復的驗證代碼；
• 你將更專注于你的業務，將這些繁瑣的事情統統丟在一邊，

3.注解介紹

JSR 380內置常用注解

Hibernate Validator 附加的 constraint

注意

• @NotNull ：適用于任何型別被注解的元素，必須不能為NULL
• @NotEmpty ：適用于String、Collection、Map或者陣列，不能為Null且長度或元素個數必須大于0
• @NotBlank：驗證字串非null，且trim后長度必須大于0

@Validated與@Valid的區別：

• @Validated注解是spring提供的，提供了一個分組功能，可以在入參驗證時，根據不同的分組采用不同的驗證機制，沒有添加分組屬性時，默認驗證沒有分組的驗證屬性（Default分組）；

• @Validated：可以用在型別、方法和方法引數上，但是不能用在成員屬性（欄位）上；

• @Validated： 用在方法入參上無法單獨提供嵌套驗證功能，也無法提示框架進行嵌套驗證，能配合嵌套驗證注解@Valid進行嵌套驗證，

• @Valid：作為標準JSR-303規范，還沒有吸收分組的功能；

• @Valid：可以用在方法、方法引數、建構式、方法引數和成員屬性（欄位）上；

• @Valid加在方法引數時并不能夠自動進行嵌套驗證，而是用在需要嵌套驗證類的相應欄位上，來配合方法引數上@Validated或@Valid來進行嵌套驗證，

4.使用

由于spring-boot-starter-web（springboot 2.3以下版本）依賴默認集成了Hibernate Validator，所以無需添加任何依賴和相關配置，只需要在專案中引入spring-boot-starter-web依賴即可（演示springboot版本為2.1.2.RELEASE），由于要用到@SafeHtml注解，這里需要加上jsoup的依賴，

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
 <!-- 決議html片段-->
<dependency>
  <groupId>org.jsoup</groupId>
  <artifactId>jsoup</artifactId>
  <version>1.8.3</version>
</dependency>

Hibernate Validator有兩種校驗模式：

• 普通模式(會校驗完所有的屬性，然后回傳所有的驗證失敗資訊，默認是這個模式)

• 快速失敗回傳模式(只要有一個欄位驗證失敗，就回傳結果)

  在@Configuration Class中配置以下代碼，將Validator設定為快速失敗回傳模式

  @Bean
      public Validator validator(){
          ValidatorFactory validatorFactory = Validation.byProvider( HibernateValidator.class)
                  .configure()
                  .addProperty( "hibernate.validator.fail_fast", "true" )
                  .buildValidatorFactory();
          Validator validator = validatorFactory.getValidator();
          return validator;
      }
  

a.物件校驗

1.在物件中添加注解

@Data
public class User {
    //注解對靜態變數不生效
    @NotBlank(message = "性別不能為空")
    private static String sex;
    
    @NotBlank(message = "姓名不能為空")
    @Size(min = 2,max = 5,message = "姓名長度不規范")
    private String name;
    
    @NotNull(message = "年齡不能為空")
    @Max(value = https://www.cnblogs.com/Scramblecode/p/30,message ="年齡超過最大值30")
    @Range(min=30,max=60)
    private Integer age;
    
    @DecimalMax(value = "https://www.cnblogs.com/Scramblecode/p/108.88",message = "超過最大108.88",inclusive = false)
    private Double price;
    
    @Past(message = "生日不能大于當前日期")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime birthday;
    
    @Email(message = "電子郵箱格式不正確")
    private String email;
    
    @SafeHtml(message = "非法請求引數")
    private String content;
}

2.進入Controller對應方法，在需要校驗的物件前添加@Valid注解即可（校驗對靜態變數不生效），在使用 @Valid 注解的引數后可以緊跟著一個 BindingResult 型別的引數，用于獲取校驗結果（將校驗結果封裝在BingdingResult物件中，不會拋出例外）

注意：@Valid 和 BindingResult 是一一對應的，如果有多個@Valid，那么每個@Valid后面跟著的BindingResult就是這個@Valid的驗證結果，順序不能亂

	//單個物件校驗
    @PostMapping("user")
    //校驗引數后邊跟BindingResult,spring不會拋出例外,將校驗結果封裝在這個物件中
    public String person(@Valid User user,BindingResult bindingResult){
        System.out.println(user);
        StringBuilder sb = new StringBuilder();
        if(bindingResult.hasErrors()){
            List<ObjectError> allErrors = bindingResult.getAllErrors();
            for(ObjectError error:allErrors){
                sb.append(error.getDefaultMessage()+",");
            }
        }
        return sb.toString();
    }

3.如果此時去掉物體物件后面的BindingResult，如校驗未通過會拋出BindException例外，需要在全域例外處理器中捕獲并統一處理

4.全域例外處理器配置

@RestControllerAdvice
@Slfj
@AutoConfigurationPackage
public class GlobalExceptionHandler {
    //spring-context包里面的例外
    //物體物件前不加@RequestBody注解,單個物件內屬性校驗未通過拋出的例外型別
    @ExceptionHandler(BindingException.class)
    public ResponseEntity<ExceptionResponseVO> methodArguments(BindingException e){
        log.warn("throw BindingException,{}",e);
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                .body(ExceptionResponseVO.error(NEError.INVALID_PARAMETER, e.getBindingResult().getFieldError().getDefaultMessage()));
    }
    
   	//物體物件前不加@RequestBody注解,校驗方法引數或方法回傳值時,未校驗通過時拋出的例外
    //Validation-api包里面的例外
    @ExceptionHandler(ValidationException.class)
    public ResponseEntity<ExceptionResponseVO> methodArguments(ValidationException e){
        log.warn("throw ValidationException,{}",e);
       return ResponseEntity.status(HttpStatus.BAD_REQUEST)            .body(ExceptionResponseVO.error(NEError.INVALID_PARAMETER,e.getCause().getMessage()));
    }
    
    //spring-context包里面的例外,物體物件前加@RequestBody注解,拋出的例外為該類例外
    //方法引數如果帶有@RequestBody注解，那么spring mvc會使用RequestResponseBodyMethodProcessor	  //對引數進行序列化,并對引數做校驗
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ExceptionResponseVO> methodArguments(MethodArgumentNotValidException e){
        log.warn("throw MethodArgumentNotValidException,{}",e);
       return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                .body(ExceptionResponseVO.error(NEError.INVALID_PARAMETER, 	           e.getBindingResult().getFieldError().getDefaultMessage()));
    }
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity methodArguments(Exception e){
        log.warn("throw exception,{}",e);
        return ResponseEntity.badRequest().body(e.getMessage());
    }
}

b.級聯校驗

如果一個物件內部包含另一個物件作為屬性，屬性上加 @Valid，可以驗證作為屬性的物件內部的驗證

@Data
public class User2 {
    @NotBlank(message = "姓名不能為空")
    private String name;
    @Max(value = https://www.cnblogs.com/Scramblecode/p/50,message ="年齡不能為空")
    private Integer age;
    @Valid
    @NotNull(message = "商品不能為空")
    private Goods goods;
}

@Data
public class Goods{
    @NotBlank(message = "商品名稱不能為空")
    private String goodsName;
    @NotNull(message = "商品價格不能為空")
    private Double goodsPrice;
}

如果級聯校驗內元素的屬性校驗未通過，拋出MethodArgumentNotValidException例外，注意在全域例外處理器捕獲該例外并處理

//級聯校驗
 @PostMapping("cascade")
public String cascade(@Valid @RequestBody User2 user2){
     return "OK";
 }

c.容器元素校驗

用來校驗物體物件內集合中的元素，在容器泛型前加注解，可實作對容器單個元素的校驗；如下：

@Data
public class User3 {
    @NotBlank(message = "姓名不能為空")
    private String name;
    @Max(value = https://www.cnblogs.com/Scramblecode/p/50,message ="年齡不能為空")
    private Integer age;
    
    @Valid
    @NotEmpty(message = "商品串列不能為空")
    private List<@NotNull(message = "商品不能為空") Goods> goodsList;
}

如果容器元素校驗未通過，拋出例外MethodArgumentNotValidException（與級聯校驗拋出的一樣）

//容器元素校驗
@PostMapping("container")
public String container(@Valid @RequestBody User3 user3){
    return "OK";
}

d.方法的校驗

JSR 303標準定義介面ExecutableValidator，用來校驗方法引數，Hibernate Validator實作了該介面（ValidatorImpl.class），不僅對Object的屬性進行校驗，還可以對方法引數、回傳值、建構式引數等進行校驗；Spring 在此基礎上進行了擴展，添加了MethodValidationPostProcessor攔截器，通過AOP實作對方法的校驗；此時拋出的例外是javax.validation.ConstraintViolationException

注意 ：必須在Controller上面加上注解@Validated，否則校驗規則無效

@RestController
@RequestMapping("validator")
@Validated
public class ValidatorController {
	@GetMapping("demo1")
    public String test1(@Range(min = 1,max = 999,message = "起始筆數超過區間范圍")@RequestParam int pageIndex, @Range(min = 1,max = 999,message = "查詢筆數超過區間范圍"）@RequestParam int pageSize){
        return "ok";
    }
}

除了校驗Controller方法外，也可校驗Service（必須是單例的bean，否則不生效，因為方法引數校驗邏輯底層用AOP來實作）等方法，用法如下：

@Service
@Validated
public class UserService {
	//校驗方法引數
    public String queryUserName(@NotNull(message = "用戶引數不能為空") User user){
        return user.getName();
    }
    
    //校驗方法回傳值
    @NotNull(message = "用戶資訊不存在")
    public User queryUser(User user){
        return null;
    }
}

e.分組校驗的實作

分組

同一個校驗規則，不可能適用于所有的業務場景，對每一個業務場景去撰寫一個校驗規則，又顯得特別冗余，實際上我們可以用到Hibernate-Validator的分組功能，達到對不同場景做出不同的校驗邏輯，減少DTO物件的創建，

比如一個User物件，新增的時候不需要檢驗id（系統生成），修改的時候需要檢驗id屬性，要想復用Class，就可以使用Hibernate Validator的分組，

實體代碼：

@Data
public class UserGroup {
    @NotNull(message = "id不能為空",groups = UpdateUser.class)
    private Integer id;
    @NotBlank(message = "姓名不能為空",groups = AddUser.class)
    private String name;
    @NotNull(message = "年齡不能為空",groups = AddUser.class)
    private Integer age;

    public interface AddUser{}
    public interface UpdateUser{}
}

添加用戶：在需要校驗的物件前面加@Validated注解（不能使用@Valid注解），并配置分組class，此時AddUser的分組校驗規則生效，

	//分組校驗:添加用戶
    @PostMapping("addUser")
    public String addUser(@Validated(UserGroup.AddUser.class) UserGroup userGroup){
        return "OK";
    }

修改用戶：配置UpdateUser分組

	//分組校驗:修改用戶
    @PostMapping("updateUser")
    public String updateUser(@Validated(UserGroup.UpdateUser.class) UserGroup userGroup){
        return "OK";
    }

使用分組能極大的復用需要驗證的Class資訊，而不是按業務重復撰寫冗余的類，

注意：如果指定了校驗組，則該屬性將不再屬于默認的校驗組Default.class，則在省略校驗組引數的情況下，將不會校驗自定義校驗組的屬性，

組序列

除了按組指定是否驗證之外，還可以指定組的驗證順序，前面組驗證不通過的，后面組不進行驗證；其中@GroupSequence提供組序列的形式進行順序式校驗，即先校驗@Save分組的，如果校驗不通過就不進行后續的校驗分組了，我認為順序化的校驗，場景更多的是在業務處理類，例如聯動的屬性驗證，值的有效性很大程度上不能從代碼的列舉或常量類中來校驗，

實體代碼：

@Data
public class UserDTO {
    @NotNull(message = "id不能為空",groups = {UpdateUser.class})
    private Integer id;
    @NotBlank(message = "姓名不能為空",groups = {AddUser.class})
    private String name;
    @NotNull(message = "年齡不能為空",groups = {AddUser.class})
    private Integer age;
    @NotNull(message = "版本不能為空")//不配置goups，默認就是Default分組
    private Integer version;

	@GroupSequence({AddUser.class, UpdateUser.class, Default.class})
    public interface AddUpdateGroup{}
    public interface AddUser{}
    public interface UpdateUser{}
}

首先校驗AddUser分組的注解，如果AddUser校驗不通過，就不會去校驗UpdateUser和Default的分組

@PostMapping("user")
public String saveUser(@Validated(UserDTO.AddUpdateGroup.class) UserDTO userDTO){
	userMapper.addUser(userDTO);
    return "ok";
}

5.自定義constraint

一般情況，自定義驗證可以解決很多問題；某些業務場景下又需要做一些特別的引數校驗，此時，我們可以實作validator的介面，自定義驗證器，

創建自定義注解@Sex，該注解是放在欄位上的，也可以根據業務場景放在方法或者Class上面）用于判斷性別是否符合約束

@Target({ ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = SexConstraintValidator.class)
public @interface Sex {

    String message() default "性別引數有誤";

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

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

創建自定義驗證器

public class SexConstraintValidator
        implements ConstraintValidator<Sex,String> {
    /**
     * 性別約束邏輯
     * @param value
     * @param constraintValidatorContext
     * @return
     */
    @Override
    public boolean isValid(String value, ConstraintValidatorContext constraintValidatorContext) {
        //如果value為null,那么該校驗規則不生效;可搭配@NotNull注解使用,更加靈活
        if(value =https://www.cnblogs.com/Scramblecode/p/= null){
            return true;
        }
        return"男".equals(value) || "女".equals(value);
    }
}

要驗證的DTO物件

@Data
public class UserDTO {
    @NotNull(message = "id不能為空")
    private Integer id;
    @NotBlank(message = "姓名不能為空")
    private String name;
    @NotNull(message = "年齡不能為空")
    private Integer age;
    @NotNull(message = "版本不能為空")
    private Integer version;
    @Sex
    private String sex;
}

在UserDTO物件前加@Valid注解，可實作對性別欄位的合法性校驗，sex只能傳入“男“或“女”，

這只是一個小例子，大家可以根據業務場景自定義引數校驗器，例如敏感詞校驗、預防sql注入、js腳本攻擊等等，都可以用自定義校驗器來完成，

關注我了解更多

標籤：Java

上一篇：31 包裝類

下一篇：Spring學習02