对于最新的稳定版本，请使用 Spring Data JPA 3.3.1！Spring中文文档

对于最新的稳定版本，请使用 Spring Data JPA 3.3.1！Spring中文文档

介绍

本章介绍示例查询，并说明如何使用它。Spring中文文档

按示例查询 （QBE） 是一种用户友好的查询技术，具有简单的界面。 它允许创建动态查询，并且不需要编写包含字段名称的查询。 事实上，按示例查询根本不需要使用特定于存储的查询语言编写查询。Spring中文文档

本章介绍示例查询的核心概念。 该信息是从 Spring Data Commons 模块中提取的。 根据您的数据库，字符串匹配支持可能会受到限制。
本章介绍示例查询的核心概念。 该信息是从 Spring Data Commons 模块中提取的。 根据您的数据库，字符串匹配支持可能会受到限制。

用法

按示例查询 API 由四个部分组成：Spring中文文档

  • Probe：具有填充字段的域对象的实际示例。Spring中文文档

  • ExampleMatcher：包含有关如何匹配特定字段的详细信息。 它可以在多个示例中重复使用。ExampleMatcherSpring中文文档

  • Example： An 由探头和 . 它用于创建查询。ExampleExampleMatcherSpring中文文档

  • FetchableFluentQuery：A 提供了一个流畅的 API，允许进一步自定义派生自 . 使用 Fluent API，您可以为查询指定排序、投影和结果处理。FetchableFluentQueryExampleSpring中文文档

按示例查询非常适合以下几个用例：Spring中文文档

按示例查询还具有以下几个限制：Spring中文文档

  • 不支持嵌套或分组属性约束，例如 .firstname = ?0 or (firstname = ?1 and lastname = ?2)Spring中文文档

  • 特定于存储的字符串匹配支持。 根据数据库的不同，字符串匹配可以支持字符串的 starts/contains/ends/regex。Spring中文文档

  • 与其他属性类型完全匹配。Spring中文文档

在开始使用“按示例查询”之前，您需要有一个域对象。 若要开始，请为存储库创建一个接口，如以下示例所示：Spring中文文档

Sample Person 对象
public class Person {

  @Id
  private String id;
  private String firstname;
  private String lastname;
  private Address address;

  // … getters and setters omitted
}

前面的示例显示了一个简单的域对象。 您可以使用它来创建一个 . 默认情况下，将忽略具有值的字段，并使用特定于存储的默认值匹配字符串。ExamplenullSpring中文文档

将属性包含在“按示例查询”条件中是基于可为空性的。 除非 ExampleMatcher 忽略属性路径，否则始终包含使用基元类型 （， ， ...） 的属性。intdouble

可以使用工厂方法或使用 ExampleMatcher 生成示例。 是不可变的。 以下列表显示了一个简单的示例：ofExampleSpring中文文档

例 1.简单示例
Person person = new Person();                         (1)
person.setFirstname("Dave");                          (2)

Example<Person> example = Example.of(person);         (3)
1 创建域对象的新实例。
2 设置要查询的属性。
3 创建 .Example

您可以使用存储库运行示例查询。 为此，请让您的存储库接口扩展。 以下列表显示了该接口的摘录：QueryByExampleExecutor<T>QueryByExampleExecutorSpring中文文档

这QueryByExampleExecutor
public interface QueryByExampleExecutor<T> {

  <S extends T> S findOne(Example<S> example);

  <S extends T> Iterable<S> findAll(Example<S> example);

  // … more functionality omitted.
}
将属性包含在“按示例查询”条件中是基于可为空性的。 除非 ExampleMatcher 忽略属性路径，否则始终包含使用基元类型 （， ， ...） 的属性。intdouble
1 创建域对象的新实例。
2 设置要查询的属性。
3 创建 .Example

示例匹配器

示例不限于默认设置。 可以使用 指定自己的字符串匹配、空处理和特定于属性的设置的默认值，如以下示例所示：ExampleMatcherSpring中文文档

例 2.具有自定义匹配的示例匹配器
Person person = new Person();                          (1)
person.setFirstname("Dave");                           (2)

ExampleMatcher matcher = ExampleMatcher.matching()     (3)
  .withIgnorePaths("lastname")                         (4)
  .withIncludeNullValues()                             (5)
  .withStringMatcher(StringMatcher.ENDING);            (6)

Example<Person> example = Example.of(person, matcher); (7)
1 创建域对象的新实例。
2 设置属性。
3 创建一个期望所有值都匹配的值。 即使没有进一步的配置，它也可以在这个阶段使用。ExampleMatcher
4 构造一个新以忽略属性路径。ExampleMatcherlastname
5 构造一个新构造以忽略属性路径并包含 null 值。ExampleMatcherlastname
6 构造一个新构造以忽略属性路径、包含 null 值并执行后缀字符串匹配。ExampleMatcherlastname
7 根据域对象和配置的 .ExampleExampleMatcher

默认情况下，要求探测器上设置的所有值都匹配。 如果要获得与隐式定义的任何谓词匹配的结果，请使用 。ExampleMatcherExampleMatcher.matchingAny()Spring中文文档

您可以为单个属性（例如“firstname”和“lastname”或嵌套属性指定“address.city”）的行为。 您可以使用匹配选项和区分大小写来调整它，如以下示例所示：Spring中文文档

配置匹配器选项
ExampleMatcher matcher = ExampleMatcher.matching()
  .withMatcher("firstname", endsWith())
  .withMatcher("lastname", startsWith().ignoreCase());
}

配置匹配器选项的另一种方法是使用 lambdas（在 Java 8 中引入）。 此方法创建一个回调，要求实现者修改匹配器。 您无需返回匹配器，因为配置选项保存在匹配器实例中。 以下示例显示了使用 lambda 的匹配器：Spring中文文档

使用 lambda 配置匹配器选项
ExampleMatcher matcher = ExampleMatcher.matching()
  .withMatcher("firstname", match -> match.endsWith())
  .withMatcher("firstname", match -> match.startsWith());
}

使用配置的合并视图创建的查询。 可以在级别设置默认匹配设置，而单个设置可以应用于特定的属性路径。 设置为“打开”的设置由属性路径设置继承，除非显式定义。 属性修补程序上的设置比默认设置具有更高的优先级。 下表描述了各种设置的范围：ExampleExampleMatcherExampleMatcherExampleMatcherSpring中文文档

表 1.设置范围ExampleMatcher
设置 范围

空处理Spring中文文档

ExampleMatcherSpring中文文档

字符串匹配Spring中文文档

ExampleMatcher和属性路径Spring中文文档

忽略属性Spring中文文档

属性路径Spring中文文档

区分大小写Spring中文文档

ExampleMatcher和属性路径Spring中文文档

价值转化Spring中文文档

属性路径Spring中文文档
1 创建域对象的新实例。
2 设置属性。
3 创建一个期望所有值都匹配的值。 即使没有进一步的配置，它也可以在这个阶段使用。ExampleMatcher
4 构造一个新以忽略属性路径。ExampleMatcherlastname
5 构造一个新构造以忽略属性路径并包含 null 值。ExampleMatcherlastname
6 构造一个新构造以忽略属性路径、包含 null 值并执行后缀字符串匹配。ExampleMatcherlastname
7 根据域对象和配置的 .ExampleExampleMatcher
表 1.设置范围ExampleMatcher
设置 范围

空处理Spring中文文档

ExampleMatcherSpring中文文档

字符串匹配Spring中文文档

ExampleMatcher和属性路径Spring中文文档

忽略属性Spring中文文档

属性路径Spring中文文档

区分大小写Spring中文文档

ExampleMatcher和属性路径Spring中文文档

价值转化Spring中文文档

属性路径Spring中文文档

Fluent API

QueryByExampleExecutor提供了另一种方法，到目前为止我们还没有提到：. 与其他方法一样，它执行派生自 . 但是，使用第二个参数，您可以控制该执行的方面，否则无法动态控制。 您可以通过调用第二个参数中的各种方法来执行此操作。 允许您指定结果的顺序。 允许您指定要将结果转换为的类型。 限制查询的属性。、 、 、<S extends T, R> R findBy(Example<S> example, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction)ExampleFetchableFluentQuerysortByasprojectfirstfirstValueoneoneValueallpagestreamcountexistsSpring中文文档

使用 Fluent API 获取可能众多结果中的最后一个，按姓氏排序。
Optional<Person> match = repository.findBy(example,
    q -> q
        .sortBy(Sort.by("lastname").descending())
        .first()
);

在 Spring Data JPA 中，您可以将 Query by Example 与存储库一起使用，如以下示例所示：Spring中文文档

例 3.使用存储库按示例查询
public interface PersonRepository extends JpaRepository<Person, String> { … }

public class PersonService {

  @Autowired PersonRepository personRepository;

  public List<Person> findPeople(Person probe) {
    return personRepository.findAll(Example.of(probe));
  }
}
目前，只有属性可用于属性匹配。SingularAttribute

属性说明符接受属性名称（如 和 ）。您可以通过将属性与点 （） 链接在一起来导航。您还可以使用匹配选项和区分大小写来调整它。firstnamelastnameaddress.citySpring中文文档

下表显示了您可以使用的各种选项，以及在名为 ： 的字段上使用这些选项的结果：StringMatcherfirstnameSpring中文文档

表 2. 选项StringMatcher
匹配 合乎逻辑的结果

DEFAULT（区分大小写）Spring中文文档

firstname = ?0Spring中文文档

DEFAULT（不区分大小写）Spring中文文档

LOWER(firstname) = LOWER(?0)Spring中文文档

EXACT（区分大小写）Spring中文文档

firstname = ?0Spring中文文档

EXACT（不区分大小写）Spring中文文档

LOWER(firstname) = LOWER(?0)Spring中文文档

STARTING（区分大小写）Spring中文文档

firstname like ?0 + '%'Spring中文文档

STARTING（不区分大小写）Spring中文文档

LOWER(firstname) like LOWER(?0) + '%'Spring中文文档

ENDING（区分大小写）Spring中文文档

firstname like '%' + ?0Spring中文文档

ENDING（不区分大小写）Spring中文文档

LOWER(firstname) like '%' + LOWER(?0)Spring中文文档

CONTAINING（区分大小写）Spring中文文档

firstname like '%' + ?0 + '%'Spring中文文档

CONTAINING（不区分大小写）Spring中文文档

LOWER(firstname) like '%' + LOWER(?0) + '%'Spring中文文档
JPA 不支持正则表达式匹配。
目前，只有属性可用于属性匹配。SingularAttribute
表 2. 选项StringMatcher
匹配 合乎逻辑的结果

DEFAULT（区分大小写）Spring中文文档

firstname = ?0Spring中文文档

DEFAULT（不区分大小写）Spring中文文档

LOWER(firstname) = LOWER(?0)Spring中文文档

EXACT（区分大小写）Spring中文文档

firstname = ?0Spring中文文档

EXACT（不区分大小写）Spring中文文档

LOWER(firstname) = LOWER(?0)Spring中文文档

STARTING（区分大小写）Spring中文文档

firstname like ?0 + '%'Spring中文文档

STARTING（不区分大小写）Spring中文文档

LOWER(firstname) like LOWER(?0) + '%'Spring中文文档

ENDING（区分大小写）Spring中文文档

firstname like '%' + ?0Spring中文文档

ENDING（不区分大小写）Spring中文文档

LOWER(firstname) like '%' + LOWER(?0)Spring中文文档

CONTAINING（区分大小写）Spring中文文档

firstname like '%' + ?0 + '%'Spring中文文档

CONTAINING（不区分大小写）Spring中文文档

LOWER(firstname) like '%' + LOWER(?0) + '%'Spring中文文档
JPA 不支持正则表达式匹配。