按示例查询

Doubao 中英对照 Query by Example

介绍

本章介绍按示例查询，并说明如何使用它。

按示例查询（Query by Example，QBE）是一种用户友好、接口简单的查询技术。它支持动态创建查询，不要求您编写包含字段名的查询。事实上，按示例查询根本不要求您使用特定存储的查询语言来编写查询。

备注

本章讲解按示例查询的核心概念。相关信息摘自 Spring Data Commons 模块。根据您所使用的数据库不同，字符串匹配的支持可能有限。

用法

按示例查询 API 由四部分组成：

• 探针（Probe）：已填充字段的领域对象的实际示例。

• ExampleMatcher：ExampleMatcher 携带关于如何匹配特定字段的详细信息。它可以在多个 Example 之间复用。

• Example：一个 Example 由探针和 ExampleMatcher 组成。它用于创建查询。

• FetchableFluentQuery：FetchableFluentQuery 提供流式 API，允许对从 Example 派生的查询做进一步自定义。使用流式 API，您可以为查询指定排序投影和结果处理。

按示例查询非常适用于以下几种用例：

• 使用一组静态或动态约束查询您的数据存储。

• 频繁重构领域对象，而不必担心破坏现有查询。

• 独立于底层数据存储 API 进行工作。

按示例查询也有若干限制：

• 不支持嵌套或分组的属性约束，例如 firstname = ?0 or (firstname = ?1 and lastname = ?2)。

• 不支持匹配集合或映射。

• 字符串匹配上的特定存储支持。根据您所用数据库的不同，字符串匹配可支持开头/包含/结尾/正则等方式。

• 对其他属性类型采用精确匹配。

在开始使用按示例查询之前，您需要有一个领域对象。首先，请为您的仓库创建一个接口，如下例所示：

public class Person {

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

  // … getters and setters omitted
}

java

前述示例展示了一个简单的领域对象。您可以用它来创建一个 Example。默认情况下，值为 null 的字段会被忽略，字符串则使用特定存储的默认方式进行匹配。

备注

属性是否纳入按示例查询的条件，取决于其可空性。使用基本类型（int、double 等）的属性总会被纳入，除非 ExampleMatcher 忽略了该属性路径。

可以使用 of 工厂方法，或使用 ExampleMatcher 来构建 Example。Example 是不可变的。以下代码清单展示了一个简单的 Example：

示例 1. 简单的 Example

Person person = new Person();                         1
person.setFirstname("Dave");                          2

Example<Person> example = Example.of(person);         3

java

• 创建领域对象的新实例。

• 设置要查询的属性。

• 创建 Example。

您可以使用仓库来运行按示例查询。为此，请让您的仓库接口继承 QueryByExampleExecutor<T>。以下代码清单展示了 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.
}

java

Example 匹配器

Example 并不局限于默认设置。您可以使用 ExampleMatcher 为字符串匹配、空值处理以及特定属性的设置指定自己的默认值，如下例所示：

示例 2. 带有自定义匹配方式的 Example 匹配器

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

java

• 创建领域对象的新实例。

• 设置属性。

• 创建一个 ExampleMatcher，要求所有值都匹配。即便不做进一步配置，它在此阶段也可使用。

• 构建一个新的 ExampleMatcher，以忽略 lastname 属性路径。

• 构建一个新的 ExampleMatcher，以忽略 lastname 属性路径并纳入空值。

• 构建一个新的 ExampleMatcher，以忽略 lastname 属性路径、纳入空值，并执行后缀字符串匹配。

• 基于领域对象和已配置的 ExampleMatcher 创建一个新的 Example。

默认情况下，ExampleMatcher 要求探针上设置的所有值都匹配。如果您希望得到匹配任一隐式定义谓词的结果，请使用 ExampleMatcher.matchingAny()。

您可以为单个属性（例如 "firstname" 和 "lastname"，或对于嵌套属性的 "address.city"）指定行为。您可以通过匹配选项和大小写敏感性来调整它，如下例所示：

ExampleMatcher matcher = ExampleMatcher.matching()
  .withMatcher("firstname", endsWith())
  .withMatcher("lastname", startsWith().ignoreCase());
}

java

另一种配置匹配器选项的方式是使用 lambda（Java 8 引入）。这种方式会创建一个回调，要求实现者修改匹配器。您无需返回匹配器，因为配置选项保存在匹配器实例内部。以下示例展示了一个使用 lambda 的匹配器：

ExampleMatcher matcher = ExampleMatcher.matching()
  .withMatcher("firstname", match -> match.endsWith())
  .withMatcher("firstname", match -> match.startsWith());
}

java

由 Example 创建的查询使用配置的合并视图。默认匹配设置可在 ExampleMatcher 级别设置，而个别设置可应用于特定属性路径。在 ExampleMatcher 上设置的设置会被属性路径设置继承，除非属性路径显式定义了相应设置。属性路径上的设置优先级高于默认设置。下表描述了各种 ExampleMatcher 设置的作用范围：

表 1. ExampleMatcher 设置的作用范围

设置	作用范围
空值处理	ExampleMatcher
字符串匹配	ExampleMatcher 与属性路径
忽略属性	属性路径
大小写敏感性	ExampleMatcher 与属性路径
值转换	属性路径

流式 API

QueryByExampleExecutor 定义了流式查询方法，用于通过 findBy(Example<S> example, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction) 灵活地执行基于 Example 实例的查询。

与其他方法一样，它执行从 Example 派生的查询。不过，查询函数让您能够掌控查询执行中那些原本无法动态控制的方面。您可以通过调用 FetchableFluentQuery 的各种中间方法和终结方法来做到这一点。

中间方法

• sortBy：为结果应用排序。重复调用该方法会追加每个 Sort（请注意，使用带排序的 Pageable 的 page(Pageable) 会覆盖之前的任何排序顺序）。

• limit：限制结果数量。

• as：指定要读取或投影到的类型。

• project：限制查询的属性。

终结方法

• first、firstValue：返回第一个值。first 返回一个 Optional<T>；如果查询未产生任何结果，则返回 Optional.empty()。firstValue 是其可空变体，无需使用 Optional。

• one、oneValue：返回唯一一个值。one 返回一个 Optional<T>；如果查询未产生任何结果，则返回 Optional.empty()。oneValue 是其可空变体，无需使用 Optional。如果找到多个匹配项，则抛出 IncorrectResultSizeDataAccessException。

• all：将所有结果作为 List<T> 返回。

• page(Pageable)：将所有结果作为 Page<T> 返回。

• slice(Pageable)：将所有结果作为 Slice<T> 返回。

• scroll(ScrollPosition)：使用滚动（偏移量、键集）将结果作为 Window<T> 检索。

• stream()：返回一个 Stream<T> 以惰性处理结果。该流是有状态的，使用后必须关闭。

• count 与 exists：返回匹配实体的数量，或是否存在任何匹配项。

备注

中间方法和终结方法必须在查询函数内部调用。

示例 3. 使用流式 API 获取一个按 lastname 排序的投影 Page

Page<CustomerProjection> page = repository.findBy(example,
    q -> q.as(CustomerProjection.class)
          .page(PageRequest.of(0, 20, Sort.by("lastname")))
);

java

示例 4. 使用流式 API 获取可能众多结果中的最后一个，按 lastname 排序

Optional<Customer> match = repository.findBy(example,
    q -> q.sortBy(Sort.by("lastname").descending())
          .first()
);

java

下面是一个示例：

Employee employee = new Employee(); 1
employee.name= "Frodo";

Example<Employee> example = Example.of(employee); 2

repository.findAll(example); 3

// do whatever with the result

java

• 用条件创建一个领域对象（null 字段会被忽略）。

• 使用该领域对象创建一个 Example。

• 通过仓库执行查询（若只需单项，则使用 findOne）。

这演示了如何使用领域对象构建一个简单的探针。在本例中，它将基于 Employee 对象的 name 字段等于 Frodo 进行查询。null 字段会被忽略。

Employee employee = new Employee();
employee.name = "Baggins";
employee.role = "ring bearer";

ExampleMatcher matcher = matching() 1
		.withMatcher("name", endsWith()) 2
		.withIncludeNullValues() 3
		.withIgnorePaths("role"); 4
Example<Employee> example = Example.of(employee, matcher); 5

repository.findAll(example);

// do whatever with the result

java

• 创建一个自定义的 ExampleMatcher，对所有字段进行匹配（若要匹配任一字段，请使用 matchingAny()）

• 对于 name 字段，使用一个与字段末尾匹配的通配方式

• 将列与 null 进行匹配（不要忘记，在关系型数据库中 NULL 并不等于 NULL）。

• 构建查询时忽略 role 字段。

• 将自定义的 ExampleMatcher 接入探针。

也可以对任意属性应用 withTransform()，让您在构建查询之前转换该属性。例如，您可以在创建查询之前，对基于 String 的属性应用 toUpperCase()。

当您事先并不清楚查询中需要哪些字段时，按示例查询的优势尤为突出。如果您正在网页上构建一个让用户自由挑选字段的过滤器，按示例查询就是将其灵活地转化为高效查询的绝佳方式。