1. 程式人生 > >深入瞭解資料校驗:Java Bean Validation 2.0(JSR380)

深入瞭解資料校驗:Java Bean Validation 2.0(JSR380)

每篇一句

吾皇一日不退役,爾等都是臣子

相關閱讀

【小家Java】深入瞭解資料校驗(Bean Validation):基礎類打點(ValidationProvider、ConstraintDescriptor、ConstraintValidator)


對Spring感興趣可掃碼加入wx群:`Java高工、架構師3群`(文末有二維碼)

前言

前幾篇文章在講Spring的資料繫結的時候,多次提到過資料校驗。可能有人認為資料校驗模組並不是那麼的重要,因為硬編碼都可以做。若是這麼想的話,那就大錯特錯了~
前面講解DataBinder的時候一個小細節,它所在的包是:org.springframework.validation

,並且在分析原始碼的時候能看到DataBinder它不僅能夠完成資料繫結,也提供了對資料校驗的支援且還儲存了校驗結果。

我以資料繫結DataBinder為引子引出了資料校驗這一塊,是想表明它的重要性。連Java都把它抽象成了JSR標準進行提出,so我認為這塊是必修課,有必要了解本章的內容。

為什麼要有資料校驗?

資料校驗 是非常常見的工作,在日常的開發中貫穿於程式碼的各個層次,從上層的View層到底層的資料層。

在此處有必要再強調一句:前面說了資料繫結並不屬於Spring MVC的專利,同樣的資料校驗也不是隻會發生在web層,它可以在任意一層,從後面的示例中你會有更深的理解

在任何時候,當你要處理一個應用程式的業務邏輯,資料校驗是你必須

要考慮和麵對的事情。應用程式必須通過某種手段來確保輸入進來的資料從語義上來講是正確的(比如生日必須是過去時,年齡必須>0等等~)。

我們知道通常情況下程式肯定是分層的,不同的層一般由不同的人來開發。若你是一個有經驗的程式設計師, 我相信你肯定見過在不同的層了都出現了相同的校驗程式碼,這就是某種意義上的垃圾程式碼。

public String queryValueByKey(String parmTemplateCode, String conditionName, String conditionKey, String resultName) {
    checkNotNull(parmTemplateCode, "parmTemplateCode not null");
    checkNotNull(conditionName, "conditionName not null");
    checkNotNull(conditionKey, "conditionKey not null");
    checkNotNull(resultName, "resultName not null");
    ...
}

從這個簡單的方法入參校驗至少能發現如下問題:

  1. 需要寫大量的程式碼來進行引數驗證。(這種程式碼多了就算垃圾程式碼)
  2. 需要通過註釋來知道每個入參的約束是什麼(否則別人咋看得懂)
  3. 每個程式設計師做引數驗證的方式不一樣,引數驗證不通過丟擲的異常也不一樣(後期幾乎沒法維護)

如上會導致程式碼冗餘和一些管理的問題(程式碼量越大,管理起來維護起來就越困難),比如說語義的一致性等。為了避免這樣的情況發生,最好是將驗證邏輯與相應的域模型(領域模型的概念)進行繫結,這就是本文提供的一個新思路(其實是JavaEE提供的思路)

為了解決這個問題,Bean ValidationJavaBean 驗證定義了相應的元資料模型和 API。預設的元資料是 各種Java Annotations,當然也支援xml方式並且你也可以擴充套件~
可以說Bean ValidationJavaBean的一個拓展,它可以佈局於任意一層程式碼,不侷限於Web應用還是端應用。

Java Bean Validation

JSR是Java Specification Requests的縮寫,意思是Java 規範提案。關於資料校驗這塊,最新的是JSR380,也就是我們常說的Bean Validation 2.0

Bean Validation 2.0 是JSR第380號標準。該標準連線如下:https://www.jcp.org/en/egc/view?id=380
Bean Validation的主頁:http://beanvalidation.org
Bean Validation的參考實現:https://github.com/hibernate/hibernate-validator

Bean Validation是一個通過配置註解來驗證引數的框架,它包含兩部分Bean Validation API(規範)和Hibernate Validator(實現)。
Bean Validation是Java定義的一套基於註解/xml的資料校驗規範,目前已經從JSR 303的1.0版本升級到JSR 349的1.1版本,再到JSR 380的2.0版本(2.0完成於2017.08),已經經歷了三個版本(我截圖如下:)

現在絕大多數coder使用者其實都還在使用Bean Validation 1.1,畢竟一般來說它已經夠用了~
本文會介紹Bean Validation 2.0提供的一些實用的新東西,畢竟Java8現在已成為主流,完全可以使用了~

簡單Demo示例

要想使用它,首先就得導包嘛~根據經驗,和JCache類似Java只提供了規範,並沒有提供實現,所以我們可以先找到它的API包然後匯入:

<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <!-- <version>1.1.0.Final</version> -->
    <version>2.0.1.Final</version>
</dependency>

關於版本之間的差異其實不是本文說明的重點,畢竟2.0做到了很好的向下相容,使用起來是無縫的。
但是本處還是給個1.1版本和2.0.1的截圖,感官上簡單對比一下區別:

相容性表格

Bean Validation Hibernate Validation JDK Spring Boot
1.1 5.4 + 6+ 1.5.x
2.0 6.0 + 8+ 2.0.x

關於Bean Validation 2.0的關注點(新特性)

因為2.0推出的時間確實不算長,so此處我把一些重要的關注點列舉如下:

  1. 對Java的最低版本要求是Java 8
  2. 支援容器的校驗,通過TYPE_USE型別的註解實現對容器內容的約束:List<@Email String>
  3. 支援日期/時間的校驗,@Past@Future
  4. 拓展元資料(新增註解):@Email,@NotEmpty,@NotBlank,@Positive, @PositiveOrZero,@Negative,@NegativeOrZero,@PastOrPresent和@FutureOrPresent
    1. 像@Email、@NotEmpty、@NotBlank之前是Hibernate額外提供的,2.0標準後hibernate自動退位讓賢並且標註為過期了
  5. Bean Validation 2.0的唯一實現為Hibernate Validator。(其實還有Apache BVal,但是你懂的,forget it)
  6. 對於Hibernate Validator,它自己也擴充套件了一些註解支援。
    1. 6.0以上版本新增(對應標準2.0版本):@UniqueElements、@ISBN、@CodePointLength、、、、、、、、
    2. 6.0以下版本可以使用的: @URL、@ScriptAssert、@SafeHtml、@Range、@ParameterScriptAssert、@Mod11Check、@Mod10Check、@LuhnCheck、@Length、@EAN、@Currency、@CreditCardNumber、@ConstraintComposition、@DurationMax、@DurationMin、**@REGON、@PESEL、@NIP、@TituloEleitoral、@CPF、@CNPJ**
    3. Hibernate Validator預設會校驗完所有的屬性,然後返回所有的驗證失敗資訊。開啟fail fast mode後,只要有一個驗證失敗,則返回驗證失敗資訊。

so,對於Java Bean Validation的實現落地產品就沒啥好選的,匯入Hibernate Validator(最新版本)吧:

<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.0.17.Final</version>
</dependency>

==小細節:==

可以看到,匯入了hibernate-validator就必要再自己匯入Java Bean ValidationAPI了,因此建議不用再手動匯入API,交給內部來管理依賴。

定義一個待校驗的普通JavaBean:

@Getter
@Setter
@ToString
public class Person {

    // 錯誤訊息message是可以自定義的
    @NotNull(message = "名字不能為null")
    public String name;
    @Positive
    public Integer age;

    @NotNull
    @NotEmpty
    private List<@Email String> emails;
    @Future
    private Date start;

}

書寫測試用例:

    public static void main(String[] args) {
        Person person = new Person();
        //person.setName("fsx");
        person.setAge(-1);
        // email校驗:雖然是List都可以校驗哦
        person.setEmails(Arrays.asList("[email protected]", "[email protected]", "aaa.com"));
        //person.setStart(new Date()); //start 需要是一個將來的時間: Sun Jul 21 10:45:03 CST 2019
        //person.setStart(new Date(System.currentTimeMillis() + 10000)); //校驗通過

        // 對person進行校驗然後拿到結果(顯然使用時預設的校驗器)   會保留下校驗失敗的訊息
        Set<ConstraintViolation<Person>> result = Validation.buildDefaultValidatorFactory().getValidator().validate(person);
        // 對結果進行遍歷輸出
        result.stream().map(v -> v.getPropertyPath() + " " + v.getMessage() + ": " + v.getInvalidValue())
                .forEach(System.out::println);
    }

執行,報錯啦:

Caused by: java.lang.ClassNotFoundException: javax.el.ELManager
    at java.net.URLClassLoader.findClass(URLClassLoader.java:382)
...

可以看到執行必須依賴於javax.el這個包。(其實我是比較費解的,為何校驗框架非得依賴它呢?有小夥伴可以幫忙解釋一下嗎?)

那行,匯入依賴javax.el以及它的實現:

<!-- 注意這裡匯入的是Apr, 2013釋出的el3.x的版本,但是glassfish並沒有對此版本進行支援了  當然tomcat肯定是支援的 -->
<dependency>
    <groupId>javax.el</groupId>
    <artifactId>javax.el-api</artifactId>
    <version>3.0.1-b06</version>
</dependency>
<!-- servlet容器大都對el有實現(支援jsp的都對此有實現),比如tomcat/glassfish等 -->
<dependency>
    <groupId>org.glassfish.web</groupId>
    <artifactId>javax.el</artifactId>
    <version>2.2.6</version>
</dependency>

需要注意的是,網上大都建議匯入org.glassfish.web包。但是EL3.0後它並沒有再提供支援了,因此我個人是不建議使用它,而是使用下面tomcat的實現的~

關於EL的實現此處囉嗦一句:JavaEE並沒有提供el的實現,需要容器自行提供,比如上面你想要匯入最為流行的tomcat,你可以匯入如下jar即可:

<!-- 嵌入式的tomcat -->
<dependency>
    <groupId>org.apache.tomcat.embed</groupId>
    <artifactId>tomcat-embed-el</artifactId>
    <version>9.0.22</version>
</dependency>
<!-- 傳統的tomcat(需要注意的是:傳統的tomcat這種jar是不需要你手動匯入的,tomcat自帶的) -->
<dependency>
    <groupId>org.apache.tomcat</groupId>
    <artifactId>tomcat-jasper-el</artifactId>
    <version>9.0.22</version>
    <scope>provided</scope>
</dependency>

此處還需要說明一點的是:嵌入式tomcat(比如SpringBoot環境)若要使用時需要顯示匯入的。但是傳統tomcat中你若要使用是不用自己匯入的(tomcat自帶此jar)。

但是,但是,但是自從tomcat8.5後不再自帶jsper-el的包了,需要手動匯入。(tomcat7還是有的~)

==最佳實踐:==
一般來說,javax.el-api以及validation-api都是沒有必要單獨匯入的,第三方包都會自帶。所以絕大數情況下,我們只需要這麼匯入即可正常work,形如下面這樣非常趕緊整潔:

<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.0.17.Final</version>
</dependency>
<dependency>
    <groupId>org.apache.tomcat.embed</groupId>
    <artifactId>tomcat-embed-el</artifactId>
    <version>9.0.22</version>
</dependency>
此處可能有夥伴會問:為何自己在使用的時候從來都沒有匯入過EL相關Jar包,也能正常資料校驗呢?

答:那是因為絕大多數情況下你使用@Valid是使用在Spring MVC上,它是不依賴於EL方式的,下篇文章會詳細說明關於資料校驗在Spring上的使用。而本文主要還是講解API的方式~

---

經過一番導包後,再次執行列印如下(方式一、方式二結果一致):

name名字不能為null: null //  此處錯誤訊息是自己的自定義內容
age必須是正數: -1
emails[2].<list element>不是一個合法的電子郵件地址: aaa.com

這樣通過API呼叫的方式就完成了對這個JavaBean的屬性校驗~

核心API分析

Validation

官方給它的定義為:This class is the entry point for Bean Validation.它作為校驗的入口,有三種方式來啟動它:

  1. 最簡單方式:使用預設的ValidatorFactory factory = Validation.buildDefaultValidatorFactory(); 雖然是預設的單也會有如下2種情況:
    1. 若使用了xml配置了一個provider,那就會使用這個provider來提供Factory
    2. 若沒有xml或者xml力沒有配置provider,那就是用預設的ValidationProviderResolver實現類來處理
  2. 方式二:選擇自定義的ValidationProviderResolver來跟XML配置邏輯選出一個ValidationProvider來。大致程式碼如下:
Configuration configuration = Validation.byDefaultProvider()
        .providerResolver(new MyResolverStrategy()) // 自定義一個ValidationProviderResolver的實現類
        .configure();
ValidatorFactory factory = configuration.buildValidatorFactory();
  1. 第三種方式就更加自由了:你可以直接提供一個型別安全的ValidationProvider實現。比如HibernateValidator就是一個ValidationProvider的實現:
HibernateValidatorConfiguration configuration = Validation.byProvider(HibernateValidator.class)
        // .providerResolver( ... ) // 因為制定了Provider,這個引數就可選了
        .configure()
        .failFast(false);
ValidatorFactory validatorFactory = configuration.buildValidatorFactory();

這三種初始化方式,在原始碼處就是對應提供的三個public static方法:

public class Validation {

    // 方式一
    public static ValidatorFactory buildDefaultValidatorFactory() {
        return byDefaultProvider().configure().buildValidatorFactory();
    }
    // 方式二
    public static GenericBootstrap byDefaultProvider() {
        return new GenericBootstrapImpl();
    }
    // 方式三
    public static <T extends Configuration<T>, U extends ValidationProvider<T>> ProviderSpecificBootstrap<T> byProvider(Class<U> providerType) {
        return new ProviderSpecificBootstrapImpl<>( providerType );
    }
    ...
}

對於若你想使用xml檔案獨立配置校驗規則,可以使用Configuration.addMapping(new FileInputStream(validationFile));,現在很少這麼使用,略~
使用注意事項:ValidatorFactory被建立後應該快取起來再提供使用,因為它是縣城安全的。

因為現在都會使用Hibernate-Validation來處理校驗,因此此處只關心方式三~

HibernateValidatorConfiguration

此介面表示配置,繼承自標註介面javax.validation.Configuration。很明顯,它是HibernateValidator的專屬配置類

先看頂級介面:javax.validation.Configuration,為構建ValidatorFactory的配置類。預設情況下,它會讀取配置檔案META-INF/validation.xml,Configuration提供的API方法是覆蓋xml配置檔案項的。若沒有找到validation.xml,就會使用預設的ValidationProviderResolver也就是:DefaultValidationProviderResolver

public interface Configuration<T extends Configuration<T>> {
    // 該方法呼叫後就不會再去找META-INF/validation.xml了
    T ignoreXmlConfiguration();
    // 訊息內插器  它是個狠角色,關於它的使用場景,後續會有詳解(包括Spring都實現了它來做事)
    // 它的作用是:插入給定的約束衝突訊息
    T messageInterpolator(MessageInterpolator interpolator);
    // 確定bean驗證提供程式是否可以訪問屬性的協定。對每個正在驗證或級聯的屬性呼叫此約定。(Spring木有實現它)
    // 對每個正在驗證或級聯的屬性都會呼叫此約定
    // Traversable: 可移動的
    T traversableResolver(TraversableResolver resolver);
    // 建立ConstraintValidator的工廠
    // ConstraintValidator:定義邏輯以驗證給定物件型別T的給定約束A。(A是個註解型別)
    T constraintValidatorFactory(ConstraintValidatorFactory constraintValidatorFactory);
    // ParameterNameProvider:提供Constructor/Method的方法名們
    T parameterNameProvider(ParameterNameProvider parameterNameProvider);
    // java.time.Clock 用作判定@Future和@Past(預設取值當前時間)
    // 若你希望他是個邏輯實現,提供一個它即可
    // @since 2.0
    T clockProvider(ClockProvider clockProvider);
    // 值提取器。這是add哦~ 負責從Optional、List等這種容器裡提取值~
    // @since 2.0
    T addValueExtractor(ValueExtractor<?> extractor);
    // 載入xml檔案
    T addMapping(InputStream stream);
    // 新增特定的屬性給Provider用的。此屬性等效於XML配置屬性。
    // 此方法通常是框架自己分析xml檔案得到屬性值然後放進去,呼叫者一般不使用(當然也可以用)
    T addProperty(String name, String value);
    
    // 下面都是get方法嘍
    MessageInterpolator getDefaultMessageInterpolator();
    TraversableResolver getDefaultTraversableResolver();
    ConstraintValidatorFactory getDefaultConstraintValidatorFactory();
    ParameterNameProvider getDefaultParameterNameProvider();
    ClockProvider getDefaultClockProvider();
    BootstrapConfiguration getBootstrapConfiguration(); // 整個配置也可返回出去

    // 上面都是工作,這個方法才是最終需要呼叫的:得到一個ValidatorFactory
    ValidatorFactory buildValidatorFactory();
}

該介面提供了一些標準的配置項。在實際應用中都是使用Hibernate Validation,所以再看看這個具體的子介面:

public interface HibernateValidatorConfiguration extends Configuration<HibernateValidatorConfiguration> {

    // 這批屬性,證明直接可以通過System屬性值來控制,大大地方便~
    // 這個機制快速失敗機制:true檢查完一個有錯誤就返回,false全部檢查完把錯誤訊息一起返回   預設false
    String FAIL_FAST = "hibernate.validator.fail_fast"; 
    String ALLOW_PARAMETER_CONSTRAINT_OVERRIDE = "hibernate.validator.allow_parameter_constraint_override";
    String ALLOW_MULTIPLE_CASCADED_VALIDATION_ON_RESULT = "hibernate.validator.allow_multiple_cascaded_validation_on_result";
    String ALLOW_PARALLEL_METHODS_DEFINE_PARAMETER_CONSTRAINTS = "hibernate.validator.allow_parallel_method_parameter_constraint";
    // @since 5.2
    @Deprecated
    String CONSTRAINT_MAPPING_CONTRIBUTOR = "hibernate.validator.constraint_mapping_contributor";
    // @since 5.3
    String CONSTRAINT_MAPPING_CONTRIBUTORS = "hibernate.validator.constraint_mapping_contributors";
    // @since 6.0.3
    String ENABLE_TRAVERSABLE_RESOLVER_RESULT_CACHE = "hibernate.validator.enable_traversable_resolver_result_cache";
    // @since 6.0.3  ScriptEvaluatorFactory:執行指令碼
    @Incubating
    String SCRIPT_EVALUATOR_FACTORY_CLASSNAME = "hibernate.validator.script_evaluator_factory";
    // @since 6.0.5 comparing date/time in temporal constraints. In milliseconds.
    @Incubating
    String TEMPORAL_VALIDATION_TOLERANCE = "hibernate.validator.temporal_validation_tolerance";

    // ResourceBundleMessageInterpolator用於 load resource bundles
    ResourceBundleLocator getDefaultResourceBundleLocator();
    // 建立一個ConstraintMapping:通過程式設計API配置的約束對映
    // 設定對映後,必須通過addMapping(constraintmapping)將其新增到此配置中。
    ConstraintMapping createConstraintMapping();
    // 拿到所有的值提取器  @since 6.0
    @Incubating
    Set<ValueExtractor<?>> getDefaultValueExtractors();

    // 往下就開始配置了~~~~~~~~~~
    HibernateValidatorConfiguration addMapping(ConstraintMapping mapping);
    HibernateValidatorConfiguration failFast(boolean failFast);
    // used for loading user-provided resources:
    HibernateValidatorConfiguration externalClassLoader(ClassLoader externalClassLoader);
    // true:表示允許覆蓋約束的方法。false表示不予許(丟擲異常)  預設值是false
    HibernateValidatorConfiguration allowOverridingMethodAlterParameterConstraint(boolean allow);
    // 定義是否允許對返回值標記多個約束以進行級聯驗證。  預設是false
    HibernateValidatorConfiguration allowMultipleCascadedValidationOnReturnValues(boolean allow);
    // 定義約束的**並行方法**是否應引發ConstraintDefinitionException
    HibernateValidatorConfiguration allowParallelMethodsDefineParameterConstraints(boolean allow);
    // 是否允許快取TraversableResolver  預設值是true
    HibernateValidatorConfiguration enableTraversableResolverResultCache(boolean enabled);
    // 設定一個指令碼執行器
    @Incubating
    HibernateValidatorConfiguration scriptEvaluatorFactory(ScriptEvaluatorFactory scriptEvaluatorFactory);
    // 允許在時間約束中比較日期/時間時設定可接受的誤差範圍
    // 比如@Past @PastOrPresent @Future @FutureOrPresent
    @Incubating
    HibernateValidatorConfiguration temporalValidationTolerance(Duration temporalValidationTolerance);
    // 允許設定將傳遞給約束驗證器的有效負載。如果多次呼叫該方法,則只傳播最後傳遞的有效負載。
    @Incubating
    HibernateValidatorConfiguration constraintValidatorPayload(Object constraintValidatorPayload);
}

關於此介面的唯一實現類:ConfigurationImpl,這裡就不用再做分析了,因為對於Validation這塊,咱們面向介面程式設計是完全沒有問題的~

準備好了Configuration後,下一步顯然就是configuration.buildValidatorFactory()來得到一個ValidatorFactory嘍,關於ValidatorFactory這塊的內容,請聽下文分解~

總結

該文講解是關於Bean Validation資料校驗,在現在Spring的高度封裝下,越來越少的人能夠主動去發現Java實現/標準了~
實際上Spring的強大並不是自己創造了多少輪子,而是它主要是帶來了更為簡單的抽象,從而減少樣板程式碼、促進解耦、提高可單測性。因此對於有些常用的功能還是建議稍微瞭解多一點,做到心中有數,運用起來也才會更加的遊刃有餘

知識交流

若文章格式混亂,可點選:原文連結-原文連結-原文連結-原文連結-原文連結

==The last:如果覺得本文對你有幫助,不妨點個讚唄。當然分享到你的朋友圈讓更多小夥伴看到也是被作者本人許可的~==

若對技術內容感興趣可以加入wx群交流:Java高工、架構師3群
若群二維碼失效,請加wx號:fsx641385712(或者掃描下方wx二維碼)。並且備註:"java入群" 字樣,會手動邀請入