一、相关接口方法

    在继承JpaRepository接口后，自动拥有了按“实例”进行查询的诸多方法。这些方法主要在两个接口中定义，一是QueryByExampleExecutor，一个是JpaRepository，如下所示：

public interface QueryByExampleExecutor
      
        { 
        S findOne(Example example); //根据“实例”查找一个对象。 Iterable findAll(Example example); //根据“实例”查找一批对象 Iterable findAll(Example example, Sort sort); //根据“实例”查找一批对象，且排序 Page findAll(Example example, Pageable pageable); //根据“实例”查找一批对象，且排序和分页 long count(Example example); //根据“实例”查找，返回符合条件的对象个数 boolean exists(Example example); //根据“实例”判断是否有符合条件的对象}
      

@NoRepositoryBean public interface JpaRepository
      
        　　extends PagingAndSortingRepository
       
        , QueryByExampleExecutor
        
          { ...... @Override 
          List findAll(Example example); //根据实例查询 @Override  List findAll(Example example, Sort sort);//根据实例查询，并排序。 }
        
       
      

二、快速入门

    观察上面的方法，其参数都有一个 Example 类对象，这就一个“实例”（个人翻译的叫法，未必准确），它代表的是查询条件，它是通过包装要查询的实体对象而生成的。下面通过一个例子，来快速了解一下其用法。

 

1、定义实体类

 如有 客户信息、客户类型 两个实体类定义如下：

/*** 客户*/@Entity@Table(name = "demo_lx_Customer")public class Customer extends BaseBo{　　private String name; //姓名　　private String sex; //性别　　private int age; //年龄　　private String address; //地址　　private boolean focus ; //是否重点关注　　private Date addTime; //创建时间　　private String remark; //备注　　@ManyToOne　　private CustomerType customerType; //客户类型　　......}

/*** 客户类型*/@Entity@Table(name = "demo_lx_CustomerType")public class CustomerType extends BaseBo{ 　　private String code; //编号　　private String name; //名称　　private String remark; //备注　　......}

2、模拟数据

加入一些模拟数据：

 

3、查询

现在要查询：地址是“郑州市”，姓“刘”的客户，可以这样来写：

//创建查询条件数据对象        Customer customer = new Customer();        customer.setName("刘");        customer.setAddress("河南省郑州市");        //创建匹配器，即如何使用查询条件        ExampleMatcher matcher = ExampleMatcher.matching() //构建对象                .withMatcher("name", GenericPropertyMatchers.startsWith()) //姓名采用“开始匹配”的方式查询                .withIgnorePaths("focus");  //忽略属性：是否关注。因为是基本类型，需要忽略掉                //创建实例        Example
        
          ex = Example.of(customer, matcher);                 //查询        List
         
           ls = dao.findAll(ex);                //输出结果        System.out.println("数量："+ls.size());        for (Customer bo:ls)        {            System.out.println(bo.getName());        }
         
        

输出结果：

数量：1刘芳

 

三、认识“实例查询”

 

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
          
            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
          
            ex = Example.of(customer);                 //查询        List
           
             ls = dao.findAll(ex);                //输出结果        System.out.println("数量："+ls.size());        for (Customer bo:ls)        {            System.out.println(bo.getName());        }
           
          

输出结果：

数量：4李明刘芳zhang mingZHANG 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
          
            ex = Example.of(customer, matcher);                 //查询        List
           
             ls = dao.findAll(ex);                //输出结果        System.out.println("数量："+ls.size());        for (Customer bo:ls)        {            System.out.println(bo.getName());        }
           
          

输出结果： 

数量：2zhang mingZHANG SAN

  

3、多级查询

要求：查询所有潜在客户

说明：主要演示多层级属性查询

//创建查询条件数据对象        CustomerType type = new CustomerType();        type.setCode("01"); //编号01代表潜在客户        Customer customer = new Customer();        customer.setCustomerType(type);                //创建匹配器，即如何使用查询条件        ExampleMatcher matcher = ExampleMatcher.matching() //构建对象                .withIgnorePaths("focus");  //忽略属性：是否关注。因为是基本类型，需要忽略掉                                //创建实例        Example
          
            ex = Example.of(customer, matcher);                 //查询        List
           
             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
          
            ex = Example.of(customer, matcher);                 //查询        List
           
             ls = dao.findAll(ex);                //输出结果        System.out.println("数量："+ls.size());        for (Customer bo:ls)        {            System.out.println(bo.getName());        }
           
          

输出结果： 

数量：2张强刘明

 

七、写在最后

对实例查询的研究及本文的写作，确入投入了精力，因此该文章也赢得了不少的点击率。

但是...但是...就实用性而言，由于“实例查询”的局限性和复杂性，在Spring Data JPA中其实是不实用的。用的最多的还是“简单查询”（因为简单，所以...）和 基于JPA Criteria 的动态查询（可以满足所有需求，没有局限性）。（仅个人观点）

简单查询的两篇博文：