版本：8.1.1

文档内容来源于 spring.io，由 springdoc.tech 翻译，版权归属于 SPRING.IO (VMware, Inc.)。可供个人学习、研究，未经许可，不得进行转载或用于商业行为。

按示例查询

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

简介​

用法​

示例匹配器​

流式 API​

简介

用法

示例匹配器

流式 API