本文看點
前言
驗證資料是貫穿所有應用程式層(從表示層到持久層)的常見任務。通常在每一層實作相同的驗證邏輯，這既費時又容易出錯。為了避免重複這些驗證，開發人員經常将驗證邏輯直接捆綁到域模型中，将域類與驗證代碼混在一起，這些驗證代碼實際上是關于類本身的中繼資料，與業務邏輯不相關。
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内置常用注解
| 注解 | 詳細資訊 |
|---|---|
| 被注釋的元素必須為 |
| 被注釋的元素必須不為 |
| |
| |
| 被注釋的元素可以是字元串、數值類型，如果元素是字元串類型，将值轉為BigDecimal類型，并與value屬性進行比對，值必須大于等于指定的value值 |
| 被注釋的元素可以是字元串、數值類型，如果元素是字元串類型，将值轉為BigDecimal類型，并與value屬性進行比對，值必須小于等于指定的value值 |
| 被注釋的元素可以是字元串、數值（可以帶小數點），将注解内value的值轉為BigDecimal類型，必須大于等于指定的最小值（可以配置是否等于value，預設是包含的） |
| 被注釋的元素可以是字元串、數值（可以帶小數點），将注解内value的值轉為BigDecimal類型，其值必須小于等于指定的最大值（可以配置是否等于value，預設是包含的） |
| 被注釋的元素的大小必須在指定的範圍内，可用于字元串、Collection、Map、數組等類型 |
| 被注釋的元素必須是一個數字，其值必須在可接受的範圍内 |
| 被注釋的元素必須是一個過去的日期 |
| 被注釋的元素必須是一個将來的日期 |
| 被注釋的元素必須符合指定的正規表達式 |
| 被注釋的元素必須是電子郵箱位址 |
| 驗證字元串非null，且trim後長度必須大于0 |
| 适用于String、Collection、Map或者數組不能為Null且長度或元素個數必須大于0 |
| @Valid | 具體作用下面會列舉 |
Hibernate Validator 附加的 constraint
| 被注釋的字元串的大小必須在指定的範圍内 |
| 根據RFC2396标準校驗注釋的字元串必須是一個的有效的url |
| 被注釋的元素必須在合适的範圍内，應用于數值或字元串 |
| 檢查帶注釋的集合是否隻包含唯一的元素。相等性是使用equals()方法确定的。 |
| 檢查帶注釋的值是否包含潛在的惡意片段，如 |
注意
- @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腳本攻擊等等，都可以用自定義校驗器來完成。
關注我了解更多