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

亂敲程式碼發表於2020-12-07

本文看點

前言

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

JSR 380——Bean Validation2.0——定義了用於實體和方法驗證的後設資料模型和API，將資料校驗邏輯通過註解的形式封裝在實體物件中。
application-layers2

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的依賴，需要手動引入）
image-20201203102541552

2.為什麼使用Hibernate Validator

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

3.註解介紹

JSR 380內建常用註解

註解 詳細資訊
@Null 被註釋的元素必須為 null
@NotNull 被註釋的元素必須不為 null
@AssertTrue 被註釋的元素必須為 true
@AssertFalse 被註釋的元素必須為 false
@Min(value) 被註釋的元素可以是字串、數值型別，如果元素是字串型別，將值轉為BigDecimal型別，並與value屬性進行比對，值必須大於等於指定的value值
@Max(value) 被註釋的元素可以是字串、數值型別，如果元素是字串型別，將值轉為BigDecimal型別，並與value屬性進行比對，值必須小於等於指定的value值
@DecimalMin(value) 被註釋的元素可以是字串、數值（可以帶小數點），將註解內value的值轉為BigDecimal型別，必須大於等於指定的最小值（可以配置是否等於value，預設是包含的）
@DecimalMax(value) 被註釋的元素可以是字串、數值（可以帶小數點），將註解內value的值轉為BigDecimal型別，其值必須小於等於指定的最大值（可以配置是否等於value，預設是包含的）
@Size(max, min) 被註釋的元素的大小必須在指定的範圍內，可用於字串、Collection、Map、陣列等型別
@Digits (integer, fraction) 被註釋的元素必須是一個數字，其值必須在可接受的範圍內
@Past 被註釋的元素必須是一個過去的日期
@Future 被註釋的元素必須是一個將來的日期
@Pattern(value) 被註釋的元素必須符合指定的正規表示式
@Email 被註釋的元素必須是電子郵箱地址
@NotBlank 驗證字串非null，且trim後長度必須大於0
@NotEmpty 適用於String、Collection、Map或者陣列不能為Null且長度或元素個數必須大於0
@Valid 具體作用下面會列舉

Hibernate Validator 附加的 constraint

註解 詳細資訊
@Length 被註釋的字串的大小必須在指定的範圍內
@URL 根據RFC2396標準校驗註釋的字串必須是一個的有效的url
@Range 被註釋的元素必須在合適的範圍內，應用於數值或字串
@UniqueElements 檢查帶註釋的集合是否只包含唯一的元素。相等性是使用equals()方法確定的。
@SafeHtml 檢查帶註釋的值是否包含潛在的惡意片段，如<script/>。如用這個註解需要引入jsoup的依賴，用來解析html程式碼

注意

  • @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 = 30,message = "年齡超過最大值30")
    @Range(min=30,max=60)
    private Integer age;
    
    @DecimalMax(value = "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 = 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 = 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 == 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指令碼攻擊等等，都可以用自定義校驗器來完成。

關注我瞭解更多

相關文章