按示例查询

Doubao 中英对照 Query by Example

介绍

本章介绍按示例查询（Query by Example），并说明如何使用它。

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

备注

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

用法

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

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

• ExampleMatcher：ExampleMatcher 携带如何匹配特定字段的详细信息。它可以跨多个示例复用。

• 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
}

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

备注

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

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

示例 1. 简单示例

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

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

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

• 设置要查询的属性。

• 创建 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.
}

示例匹配器

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

示例 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

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

• 设置属性。

• 创建一个 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());
}

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

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

由 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")))
);

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

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

在 Spring Data JPA 中，您可以将按示例查询与仓库配合使用，如下例所示：

示例 5. 使用仓库进行按示例查询

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));
  }
}

属性说明符接受属性名（例如 firstname 和 lastname）。您可以用点号将属性链接在一起来进行路径导航（address.city）。您还可以通过匹配选项和大小写敏感性来调整它。

下表展示了您可以使用的各种 StringMatcher 选项，以及在名为 firstname 的字段上使用它们所得到的结果：

表 2. StringMatcher 选项

匹配方式	逻辑结果
DEFAULT（区分大小写）	firstname = ?0
DEFAULT（不区分大小写）	LOWER(firstname) = LOWER(?0)
EXACT（区分大小写）	firstname = ?0
EXACT（不区分大小写）	LOWER(firstname) = LOWER(?0)
STARTING（区分大小写）	firstname like ?0 + '%'
STARTING（不区分大小写）	LOWER(firstname) like LOWER(?0) + '%'
ENDING（区分大小写）	firstname like '%' + ?0
ENDING（不区分大小写）	LOWER(firstname) like '%' + LOWER(?0)
CONTAINING（区分大小写）	firstname like '%' + ?0 + '%'
CONTAINING（不区分大小写）	LOWER(firstname) like '%' + LOWER(?0) + '%'

备注

JPA 不支持正则匹配。