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

亂敲程式碼發表於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指令碼攻擊等等,都可以用自定義校驗器來完成。

關注我瞭解更多

相關文章