三、認識“實例查詢”

1、概念定義:

上面例子中，是這樣創建“實例”的：Example<Customer> ex = Example.of(customer, matcher);我們看到，Example對象，由customer和matcher共同創建，為講解方便，我們先來明確一些定義。

A、實體對象：在持久化框架中與Table對應的域對象，一個對象代表數據庫表中的一條記錄，如上例中Customer對象。在構建查詢條件時，一個實體對象代表的是查詢條件中的“數值”部分。如：要查詢姓“劉”的客戶，實體對象只能存儲條件值“劉”。

B、匹配器：ExampleMatcher對象，它是匹配“實體對象”的，表示了如何使用“實體對象”中的“值”進行查詢，它代表的是“查詢方式”，解釋了如何去查的問題。如：要查詢姓“劉”的客戶，即姓名以“劉”開頭的客戶，該對象就表示了“以某某開頭的”這個查詢方式，如上例中:withMatcher("name", GenericPropertyMatchers.startsWith())

C、實例：即Example對象，代表的是完整的查詢條件。由實體對象（查詢條件值）和匹配器（查詢方式）共同創建。

再來理解“實例查詢”，顧名思義，就是通過一個例子來查詢。要查詢的是Customer對象，查詢條件也是一個Customer對象，通過一個現有的客戶對象作為例子，查詢和這個例子相匹配的對象。

2、特點及約束:

1、支持動態查詢。即支持查詢條件個數不固定的情況，如：客戶列表中有多個過濾條件，用戶使用時在“地址”查詢框中輸入了值，就需要按地址進行過濾，如果沒有輸入值，就忽略這個過濾條件。對應的實現是，在構建查詢條件Customer對象時，將address屬性值置具體的條件值或置為null。

2、不支持過濾條件分組。即不支持過濾條件用 or(或) 來連接，所有的過濾查件，都是簡單一層的用 and(並且) 連接。

3、僅支持字符串的開始/包含/結束/正則表達式匹配 和 其他屬性類型的精確匹配。查詢時，對一個要進行匹配的屬性（如：姓名 name），只能傳入一個過濾條件值，如以Customer為例，要查詢姓“劉”的客戶，“劉”這個條件值就存儲在表示條件對象的Customer對象的name屬性中，針對於“姓名”的過濾也只有這麽一個存儲過濾值的位置，沒辦法同時傳入兩個過濾值。正是由於這個限制，有些查詢是沒辦法支持的，例如要查詢某個時間段內添加的客戶，對應的屬性是 addTime，需要傳入“開始時間”和“結束時間”兩個條件值，而這種查詢方式沒有存兩個值的位置，所以就沒辦法完成這樣的查詢。

四、重點理解ExampleMatcher

1、需要考慮的因素

查詢條件的表示，有兩部分，一是條件值，二是查詢方式。條件值用實體對象（如Customer對象）來存儲，相對簡單，當頁面傳入過濾條件值時，存入相對應的屬性中，沒入傳入時，屬性保持默認值。查詢方式是用匹配器ExampleMatcher來表示，情況相對復雜些，需要考慮的因素有：

（1）Null值的處理。當某個條件值為Null,是應當忽略這個過濾條件呢，還是應當去匹配數據庫表中該字段值是Null的記錄？

（2）基本類型的處理。如客戶Customer對象中的年齡age是int型的，當頁面不傳入條件值時，它默認是0，是有值的，那是否參與查詢呢？

（3）忽略某些屬性值。一個實體對象，有許多個屬性，是否每個屬性都參與過濾？是否可以忽略某些屬性？

（4）不同的過濾方式。同樣是作為String值，可能“姓名”希望精確匹配，“地址”希望模糊匹配，如何做到？

（5）大小寫匹配。字符串匹配時，有時可能希望忽略大小寫，有時則不忽略，如何做到？

2、五個配置項

圍繞上面一系列情況，ExampleMatcher中定義了5項配置來解決這些問題。

public class ExampleMatcher {
NullHandler nullHandler; //Null值處理方式StringMatcher defaultStringMatcher; //默認字符串匹配方式boolean defaultIgnoreCase; //默認大小寫忽略方式PropertySpecifiers propertySpecifiers; //各屬性特定查詢方式Set<String> ignoredPaths; //忽略屬性列表......
}

（1）nullHandler：Null值處理方式，枚舉類型，有2個可選值，INCLUDE（包括）,IGNORE（忽略）。標識作為條件的實體對象中，一個屬性值（條件值）為Null是，是否參與過濾。當該選項值是INCLUDE時，表示仍參與過濾，會匹配數據庫表中該字段值是Null的記錄；若為IGNORE值，表示不參與過濾。

（2）defaultStringMatcher：默認字符串匹配方式，枚舉類型，有6個可選值，DEFAULT（默認，效果同EXACT）,EXACT（相等）,STARTING（開始匹配）,ENDING（結束匹配）,CONTAINING（包含，模糊匹配）,REGEX（正則表達式）。該配置對所有字符串屬性過濾有效，除非該屬性在 propertySpecifiers 中單獨定義自己的匹配方式。

（3）defaultIgnoreCase：默認大小寫忽略方式，布爾型，當值為false時，即不忽略，大小不相等。該配置對所有字符串屬性過濾有效，除非該屬性在 propertySpecifiers 中單獨定義自己的忽略大小寫方式。

（4）propertySpecifiers：各屬性特定查詢方式，描述了各個屬性單獨定義的查詢方式，每個查詢方式中包含4個元素：屬性名、字符串匹配方式、大小寫忽略方式、屬性轉換器。如果屬性未單獨定義查詢方式，或單獨查詢方式中，某個元素未定義（如：字符串匹配方式），則采用 ExampleMatcher 中定義的默認值，即上面介紹的 defaultStringMatcher 和 defaultIgnoreCase 的值。

（5）ignoredPaths：忽略屬性列表，忽略的屬性不參與查詢過濾。

3、操作方法

在ExampleMatcher中定義了一系列方式，用於設置這5項設置值，所有的設置方法均返回 ExampleMatcher 對象，所以支持鏈式編程配置。

（1）創建一個默認的 ExampleMatcher 對象。

定義：

public static ExampleMatcher matching()

默認配置如下：
A、nullHandler：IGNORE。Null值處理方式：忽略
B、defaultStringMatcher：DEFAULT。默認字符串匹配方式：默認（相等）
C、defaultIgnoreCase：false。默認大小寫忽略方式：不忽略
D、propertySpecifiers：空。各屬性特定查詢方式，空。
E、ignoredPaths：空列表。忽略屬性列表，空列表。

（2）改變Null值處理方式。

定義：
public ExampleMatcher withNullHandler(NullHandler nullHandler)
public ExampleMatcher withIncludeNullValues()
public ExampleMatcher withIgnoreNullValues()

產生效果：
改變配置項nullHandler，分別設為：指定值、INCLUDE（包括）、IGNORE（忽略）。

（3）改變默認字符串匹配方式。
定義：
public ExampleMatcher withStringMatcher(StringMatcher defaultStringMatcher)

產生效果：
改變配置項defaultStringMatcher，設為指定值。

（4）改變默認大小寫忽略方式。
定義：
public ExampleMatcher withIgnoreCase()
public ExampleMatcher withIgnoreCase(boolean defaultIgnoreCase)

產生效果：
改變配置項defaultIgnoreCase，分別設為：true，指定值。

（5）向“忽略屬性列表”中添加屬性。
定義：
public ExampleMatcher withIgnorePaths(String... ignoredPaths)

產生效果：
改變配置項ignoredPaths，向列表中添加一個或多個屬性。

（6）配置屬性特定查詢方式

一個屬性的特定查詢方式，包含了3個信息：字符串匹配方式、大小寫忽略方式、屬性轉換器，存儲在 propertySpecifiers 中，操作時用 GenericPropertyMatcher 類來傳遞配置信息。有4個方法來改變配置，這4個方法操作時，內部均采用增量改變的方式，即如果沒有為屬性定義“特定查詢方式”，則會定義一個，並根據傳進來的“非空信息”進行配置，如果已經定義有，則會根據傳進來的“非空信息”進行更新。如果一個“特定查詢方式”中的“字符串匹配方式、大小寫忽略方式”沒有設置值，查詢時則采用ExampleMatcher中的默認配置。

A、自定義類的方式。

定義：
public ExampleMatcher withMatcher(String propertyPath, MatcherConfigurer<GenericPropertyMatcher> matcherConfigurer)

產生效果：

向 propertySpecifiers 中增加或更新屬性“特定查詢方式”的配置。

參數說明：
propertyPath：要配置特定查詢的屬性名。
matcherConfigurer：自定義類對象。自定義類需要實現MatcherConfigurer接口，在接口的 configureMatcher() 實現方法中指定相關配置。

B、直接傳入通用屬性查詢對象方式。

定義：
public ExampleMatcher withMatcher(String propertyPath, GenericPropertyMatcher genericPropertyMatcher)

產生效果：

向 propertySpecifiers 中增加或更新屬性“特定查詢方式”的配置。

參數說明：
propertyPath：要配置特定查詢的屬性名。
genericPropertyMatcher：直接傳入一個通用查詢對象。 ExampleMatcher.GenericPropertyMatchers工具類中提供了常用對象創建的靜態方法，所有方法均返回 GenericPropertyMatcher 對象，所以支持鏈式編程配置。

另外：GenericPropertyMatcher 類本身也提供了諸多方法，用於改變相關配置項。

C、改變的大小寫忽略方式

定義：
public ExampleMatcher withIgnoreCase(String... propertyPaths)

產生效果：
向 propertySpecifiers 中增加或更新屬性“特定查詢方式”中的“大小寫忽略方式”配置。。

D、設置屬性轉換器

定義：
public ExampleMatcher withTransformer(String propertyPath, PropertyValueTransformer propertyValueTransformer)

產生效果：
向 propertySpecifiers 中增加或更新屬性“特定查詢方式”中的“屬性轉換器”配置。

五、常用情況說明

1、關於基本數據類型。
實體對象中，避免使用基本數據類型，采用包裝器類型。如果已經采用了基本類型，
而這個屬性查詢時不需要進行過濾，則把它添加到忽略列表（ignoredPaths）中。

2、Null值處理方式。
默認值是 IGNORE（忽略），即當條件值為null時，則忽略此過濾條件，一般業務也是采用這種方式就可滿足。當需要查詢數據庫表中屬性為null的記錄時，可將值設為INCLUDE，這時，對於不需要參與查詢的屬性，都必須添加到忽略列表（ignoredPaths）中，否則會出現查不到數據的情況。

3、默認配置、特殊配置。
默認創建匹配器時，字符串采用的是精確匹配、不忽略大小寫，可以通過操作方法改變這種默認匹配，以滿足大多數查詢條件的需要，如將“字符串匹配方式”改為CONTAINING（包含，模糊匹配），這是比較常用的情況。對於個別屬性需要特定的查詢方式，可以通過配置“屬性特定查詢方式”來滿足要求。

4、非字符串屬性
如約束中所談，非字符串屬性均采用精確匹配，即等於。

5、忽略大小寫的問題。
忽略大小的生效與否，是依賴於數據庫的。例如 MySql 數據庫中，默認創建表結構時，字段是已經忽略大小寫的，所以這個配置與否，都是忽略的。如果業務需要嚴格區分大小寫，可以改變數據庫表結構屬性來實現，具體可百度。

六、常用查詢示例

以“快速入門”中的實體對象和模擬數據為例，列一些常用查詢，方便開發時參考。

1、無匹配器的情況
要求：查詢地址是“河南省鄭州市”，且重點關註的客戶。
說明：對於默認匹配器滿足條件時，則不需要創建匹配器。

　　　　 //創建查詢條件數據對象
        Customer customer = new Customer();
        customer.setAddress("河南省鄭州市");
        customer.setFocus(true);        
        //創建實例
        Example<Customer> ex = Example.of(customer); 
        
        //查詢
        List<Customer> ls = dao.findAll(ex);        
        //輸出結果
        System.out.println("數量："+ls.size());        for (Customer bo:ls)
        {
            System.out.println(bo.getName());
        }

輸出結果：

數量：4
李明
劉芳
zhang ming
ZHANG SAN

2、通用情況
要求：根據姓名、地址、備註進行模糊查詢，忽略大小寫，地址要求開始匹配。
說明：這是通用情況，主要演示改變默認字符串匹配方式、改變默認大小寫忽略方式、屬性特定查詢方式配置、忽略屬性列表配置。

　　　　 //創建查詢條件數據對象
        Customer customer = new Customer();
        customer.setName("zhang");
        customer.setAddress("河南省");
        customer.setRemark("BB");        //創建匹配器，即如何使用查詢條件
        ExampleMatcher matcher = ExampleMatcher.matching() //構建對象
                .withStringMatcher(StringMatcher.CONTAINING) //改變默認字符串匹配方式：模糊查詢
                .withIgnoreCase(true) //改變默認大小寫忽略方式：忽略大小寫
                .withMatcher("address", GenericPropertyMatchers.startsWith()) //地址采用“開始匹配”的方式查詢
                .withIgnorePaths("focus");  //忽略屬性：是否關註。因為是基本類型，需要忽略掉        
        //創建實例
        Example<Customer> ex = Example.of(customer, matcher); 
        
        //查詢
        List<Customer> ls = dao.findAll(ex);        
        //輸出結果
        System.out.println("數量："+ls.size());        for (Customer bo:ls)
        {
            System.out.println(bo.getName());
        }

輸出結果：

數量：2
zhang ming
ZHANG SAN

3、多級查詢
要求：查詢所有潛在客戶
說明：主要演示多層級屬性查詢

　　　　 //創建查詢條件數據對象
        CustomerType type = new CustomerType();
        type.setCode("01"); //編號01代表潛在客戶
        Customer customer = new Customer();
        customer.setCustomerType(type);        

        //創建匹配器，即如何使用查詢條件
        ExampleMatcher matcher = ExampleMatcher.matching() //構建對象
                .withIgnorePaths("focus");  //忽略屬性：是否關註。因為是基本類型，需要忽略掉                
        
        //創建實例
        Example<Customer> ex = Example.of(customer, matcher); 
        
        //查詢
        List<Customer> ls = dao.findAll(ex);        
        //輸出結果
        System.out.println("數量："+ls.size());        for (Customer bo:ls)
        {
            System.out.println(bo.getName());
        }

輸出結果：

數量：4
李明
李莉
張強
ZHANG SAN

4、查詢Null值
要求：地址是null的客戶
說明：主要演示改變“Null值處理方式”

　　　　 //創建查詢條件數據對象
        Customer customer = new Customer();        //創建匹配器，即如何使用查詢條件
        ExampleMatcher matcher = ExampleMatcher.matching() //構建對象
                .withIncludeNullValues() //改變“Null值處理方式”：包括
                .withIgnorePaths("id","name","sex","age","focus","addTime","remark","customerType");  //忽略其他屬性        
        //創建實例
        Example<Customer> ex = Example.of(customer, matcher); 
        
        //查詢
        List<Customer> ls = dao.findAll(ex);        
        //輸出結果
        System.out.println("數量："+ls.size());        for (Customer bo:ls)
        {
            System.out.println(bo.getName());
        }

Spring Data JPA 實例查詢