使用spring validation完成資料後端校驗
前言
資料的校驗是互動式網站一個不可或缺的功能,前端的js校驗可以涵蓋大部分的校驗職責,如使用者名稱唯一性,生日格式,郵箱格式校驗等等常用的校驗。但是為了避免使用者繞過瀏覽器,使用http工具直接向後端請求一些違法資料,服務端的資料校驗也是必要的,可以防止髒資料落到資料庫中,如果資料庫中出現一個非法的郵箱格式,也會讓運維人員頭疼不已。我在之前保險產品研發過程中,系統對資料校驗要求比較嚴格且追求可變性及效率,曾使用drools作為規則引擎,兼任了校驗的功能。而在一般的應用,可以使用本文將要介紹的validation來對資料進行校驗。
簡述JSR303/JSR-349,hibernate validation,spring validation之間的關係。JSR303是一項標準,JSR-349是其的升級版本,添加了一些新特性,他們規定一些校驗規範即校驗註解,如@Null,@NotNull,@Pattern,他們位於javax.validation.constraints包下,只提供規範不提供實現。而hibernate validation是對這個規範的實踐(不要將hibernate和資料庫orm框架聯絡在一起),他提供了相應的實現,並增加了一些其他校驗註解,如@Email,@Length,@Range等等,他們位於org.hibernate.validator.constraints包下。而萬能的spring為了給開發者提供便捷,對hibernate validation進行了二次封裝,顯示校驗validated bean時,你可以使用spring validation或者hibernate validation,而spring validation另一個特性,便是其在springmvc模組中添加了自動校驗,並將校驗資訊封裝進了特定的類中。這無疑便捷了我們的web開發。本文主要介紹在springmvc中自動校驗的機制。
引入依賴
我們使用maven構建springboot應用來進行demo演示。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
我們只需要引入spring-boot-starter-web依賴即可,如果檢視其子依賴,可以發現如下的依賴:
<dependency> <groupId>org.hibernate</groupId> <artifactId>hibernate-validator</artifactId> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> </dependency>
驗證了我之前的描述,web模組使用了hibernate-validation,並且databind模組也提供了相應的資料繫結功能。
構建啟動類
無需新增其他註解,一個典型的啟動類
@SpringBootApplication
public class ValidateApp {
public static void main(String[] args) {
SpringApplication.run(ValidateApp.class, args);
}
}
建立需要被校驗的實體類
public class Foo {
@NotBlank
private String name;
@Min(18)
private Integer age;
@Pattern(regexp = "^1(3|4|5|7|8)\\d{9}$",message = "手機號碼格式錯誤")
@NotBlank(message = "手機號碼不能為空")
private String phone;
@Email(message = "郵箱格式錯誤")
private String email;
//... getter setter
}
使用一些比較常用的校驗註解,還是比較淺顯易懂的,欄位上的註解名稱即可推斷出校驗內容,每一個註解都包含了message欄位,用於校驗失敗時作為提示資訊,特殊的校驗註解,如Pattern(正則校驗),還可以自己新增正則表示式。
在@Controller中校驗資料
springmvc為我們提供了自動封裝表單引數的功能,一個添加了引數校驗的典型controller如下所示。
@Controller
public class FooController {
@RequestMapping("/foo")
public String foo(@Validated Foo foo <1>, BindingResult bindingResult <2>) {
if(bindingResult.hasErrors()){
for (FieldError fieldError : bindingResult.getFieldErrors()) {
//...
}
return "fail";
}
return "success";
}
}
值得注意的地方:
<1> 引數Foo前需要加上@Validated註解,表明需要spring對其進行校驗,而校驗的資訊會存放到其後的BindingResult中。注意,必須相鄰,如果有多個引數需要校驗,形式可以如下。foo(@Validated Foo foo, BindingResult fooBindingResult ,@Validated Bar bar, BindingResult barBindingResult);即一個校驗類對應一個校驗結果。
<2> 校驗結果會被自動填充,在controller中可以根據業務邏輯來決定具體的操作,如跳轉到錯誤頁面。
一個最基本的校驗就完成了,總結下框架已經提供了哪些校驗:
JSR提供的校驗註解:
@Null 被註釋的元素必須為 null
@NotNull 被註釋的元素必須不為 null
@AssertTrue 被註釋的元素必須為 true
@AssertFalse 被註釋的元素必須為 false
@Min(value) 被註釋的元素必須是一個數字,其值必須大於等於指定的最小值
@Max(value) 被註釋的元素必須是一個數字,其值必須小於等於指定的最大值
@DecimalMin(value) 被註釋的元素必須是一個數字,其值必須大於等於指定的最小值
@DecimalMax(value) 被註釋的元素必須是一個數字,其值必須小於等於指定的最大值
@Size(max=, min=) 被註釋的元素的大小必須在指定的範圍內
@Digits (integer, fraction) 被註釋的元素必須是一個數字,其值必須在可接受的範圍內
@Past 被註釋的元素必須是一個過去的日期
@Future 被註釋的元素必須是一個將來的日期
@Pattern(regex=,flag=) 被註釋的元素必須符合指定的正則表示式
Hibernate Validator提供的校驗註解:
@NotBlank(message =) 驗證字串非null,且長度必須大於0
@Email 被註釋的元素必須是電子郵箱地址
@Length(min=,max=) 被註釋的字串的大小必須在指定的範圍內
@NotEmpty 被註釋的字串的必須非空
@Range(min=,max=,message=) 被註釋的元素必須在合適的範圍內
校驗實驗
實驗告訴我們,校驗結果起了作用。並且,可以發現當發生多個錯誤,spring validation不會在第一個錯誤發生後立即停止,而是繼續試錯,告訴我們所有的錯誤。debug可以檢視到更多豐富的錯誤資訊,這些都是spring validation為我們提供的便捷特性,基本適用於大多數場景。
你可能不滿足於簡單的校驗特性,下面進行一些補充。
分組校驗
如果同一個類,在不同的使用場景下有不同的校驗規則,那麼可以使用分組校驗。未成年人是不能喝酒的,而在其他場景下我們不做特殊的限制,這個需求如何體現同一個實體,不同的校驗規則呢?
改寫註解,新增分組:
Class Foo{
@Min(value = 18,groups = {Adult.class})
private Integer age;
public interface Adult{}
public interface Minor{}
}
這樣表明,只有在Adult分組下,18歲的限制才會起作用。
Controller層改寫:
@RequestMapping("/drink")
public String drink(@Validated({Foo.Adult.class}) Foo foo, BindingResult bindingResult) {
if(bindingResult.hasErrors()){
for (FieldError fieldError : bindingResult.getFieldErrors()) {
//...
}
return "fail";
}
return "success";
}
@RequestMapping("/live")
public String live(@Validated Foo foo, BindingResult bindingResult) {
if(bindingResult.hasErrors()){
for (FieldError fieldError : bindingResult.getFieldErrors()) {
//...
}
return "fail";
}
return "success";
}
drink方法限定需要進行Adult校驗,而live方法則不做限制。
自定義校驗
業務需求總是比框架提供的這些簡單校驗要複雜的多,我們可以自定義校驗來滿足我們的需求。自定義spring validation非常簡單,主要分為兩步。
1 自定義校驗註解
我們嘗試新增一個“字串不能包含空格”的限制。
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER})
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = {CannotHaveBlankValidator.class})<1>
public @interface CannotHaveBlank {
//預設錯誤訊息
String message() default "不能包含空格";
//分組
Class<?>[] groups() default {};
//負載
Class<? extends Payload>[] payload() default {};
//指定多個時使用
@Target({FIELD, METHOD, PARAMETER, ANNOTATION_TYPE})
@Retention(RUNTIME)
@Documented
@interface List {
CannotHaveBlank[] value();
}
}
我們不需要關注太多東西,使用spring validation的原則便是便捷我們的開發,例如payload,List ,groups,都可以忽略。
<1> 自定義註解中指定了這個註解真正的驗證者類。
2 編寫真正的校驗者類
public class CannotHaveBlankValidator implements <1> ConstraintValidator<CannotHaveBlank, String> {
@Override
public void initialize(CannotHaveBlank constraintAnnotation) {
}
@Override
public boolean isValid(String value, ConstraintValidatorContext context <2>) {
//null時不進行校驗
if (value != null && value.contains(" ")) {
<3>
//獲取預設提示資訊
String defaultConstraintMessageTemplate = context.getDefaultConstraintMessageTemplate();
System.out.println("default message :" + defaultConstraintMessageTemplate);
//禁用預設提示資訊
context.disableDefaultConstraintViolation();
//設定提示語
context.buildConstraintViolationWithTemplate("can not contains blank").addConstraintViolation();
return false;
}
return true;
}
}
<1> 所有的驗證者都需要實現ConstraintValidator介面,它的介面也很形象,包含一個初始化事件方法,和一個判斷是否合法的方法。
public interface ConstraintValidator<A extends Annotation, T> {
void initialize(A constraintAnnotation);
boolean isValid(T value, ConstraintValidatorContext context);
}
<2> ConstraintValidatorContext 這個上下文包含了認證中所有的資訊,我們可以利用這個上下文實現獲取預設錯誤提示資訊,禁用錯誤提示資訊,改寫錯誤提示資訊等操作。
<3> 一些典型校驗操作,或許可以對你產生啟示作用。
值得注意的一點是,自定義註解可以用在METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER
之上,ConstraintValidator的第二個泛型引數T,是需要被校驗的型別。
手動校驗
可能在某些場景下需要我們手動校驗,即使用校驗器對需要被校驗的實體發起validate,同步獲得校驗結果。理論上我們既可以使用Hibernate Validation提供Validator,也可以使用Spring對其的封裝。在spring構建的專案中,提倡使用經過spring封裝過後的方法,這裡兩種方法都介紹下:
Hibernate Validation:
Foo foo = new Foo();
foo.setAge(22);
foo.setEmail("000");
ValidatorFactory vf = Validation.buildDefaultValidatorFactory();
Validator validator = vf.getValidator();
Set<ConstraintViolation<Foo>> set = validator.validate(foo);
for (ConstraintViolation<Foo> constraintViolation : set) {
System.out.println(constraintViolation.getMessage());
}
由於依賴了Hibernate Validation框架,我們需要呼叫Hibernate相關的工廠方法來獲取validator例項,從而校驗。
在spring framework文件的Validation相關章節,可以看到如下的描述:
Spring provides full support for the Bean Validation API. This includes convenient support for bootstrapping a JSR-303/JSR-349 Bean Validation provider as a Spring bean. This allows for a javax.validation.ValidatorFactory or javax.validation.Validator to be injected wherever validation is needed in your application. Use the LocalValidatorFactoryBean to configure a default Validator as a Spring bean:
bean id=”validator” class=”org.springframework.validation.beanvalidation.LocalValidatorFactoryBean”
The basic configuration above will trigger Bean Validation to initialize using its default bootstrap mechanism. A JSR-303/JSR-349 provider, such as Hibernate Validator, is expected to be present in the classpath and will be detected automatically.
上面這段話主要描述了spring對validation全面支援JSR-303、JSR-349的標準,並且封裝了LocalValidatorFactoryBean作為validator的實現。值得一提的是,這個類的責任其實是非常重大的,他相容了spring的validation體系和hibernate的validation體系,也可以被開發者直接呼叫,代替上述的從工廠方法中獲取的hibernate validator。由於我們使用了springboot,會觸發web模組的自動配置,LocalValidatorFactoryBean已經成為了Validator的預設實現,使用時只需要自動注入即可。
@Autowired
Validator globalValidator; <1>
@RequestMapping("/validate")
public String validate() {
Foo foo = new Foo();
foo.setAge(22);
foo.setEmail("000");
Set<ConstraintViolation<Foo>> set = globalValidator.validate(foo);<2>
for (ConstraintViolation<Foo> constraintViolation : set) {
System.out.println(constraintViolation.getMessage());
}
return "success";
}
<1> 真正使用過Validator介面的讀者會發現有兩個介面,一個是位於javax.validation包下,另一個位於org.springframework.validation包下,注意我們這裡使用的是前者javax.validation,後者是spring自己內建的校驗介面,LocalValidatorFactoryBean同時實現了這兩個介面。
<2> 此處校驗介面最終的實現類便是LocalValidatorFactoryBean。
基於方法校驗
@RestController
@Validated <1>
public class BarController {
@RequestMapping("/bar")
public @NotBlank <2> String bar(@Min(18) Integer age <3>) {
System.out.println("age : " + age);
return "";
}
@ExceptionHandler(ConstraintViolationException.class)
public Map handleConstraintViolationException(ConstraintViolationException cve){
Set<ConstraintViolation<?>> cves = cve.getConstraintViolations();<4>
for (ConstraintViolation<?> constraintViolation : cves) {
System.out.println(constraintViolation.getMessage());
}
Map map = new HashMap();
map.put("errorCode",500);
return map;
}
}
<1> 為類新增@Validated註解
<2> <3> 校驗方法的返回值和入參
<4> 新增一個異常處理器,可以獲得沒有通過校驗的屬性相關資訊
基於方法的校驗,個人不推薦使用,感覺和專案結合的不是很好。
使用校驗框架的一些想法
理論上spring validation可以實現很多複雜的校驗,你甚至可以使你的Validator獲取ApplicationContext,獲取spring容器中所有的資源,進行諸如資料庫校驗,注入其他校驗工具,完成組合校驗(如前後密碼一致)等等操作,但是尋求一個易用性和封裝複雜性之間的平衡點是我們作為工具使用者應該考慮的,我推崇的方式,是僅僅使用自帶的註解和自定義註解,完成一些簡單的,可複用的校驗。而對於複雜的校驗,則包含在業務程式碼之中,畢竟如使用者名稱是否存在這樣的校驗,僅僅依靠資料庫查詢還不夠,為了避免併發問題,還是得加上唯一索引之類的額外工作,不是嗎?