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

示例查询

DeepSeek V3 中英对照 Query by Example

引言

本章介绍了按示例查询（Query by Example）的基本概念，并解释了如何使用它。

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

备注

本章解释了 Query by Example 的核心概念。这些信息来源于 Spring Data Commons 模块。根据你的数据库，字符串匹配支持可能会受到限制。

用法

Query by Example API 由四部分组成：

Probe（探针）：一个填充了字段的领域对象实例。
ExampleMatcher（示例匹配器）：ExampleMatcher 包含了如何匹配特定字段的详细信息。它可以在多个示例中重复使用。
Example（示例）：一个 Example 由探针和 ExampleMatcher 组成。它用于创建查询。
FetchableFluentQuery（可获取的流式查询）：FetchableFluentQuery 提供了一个流式 API，允许对从 Example 派生的查询进行进一步定制。使用流式 API 可以指定查询的排序、投影和结果处理。

按示例查询适用于多种用例：

使用一组静态或动态约束查询您的数据存储。
频繁重构领域对象，而不用担心破坏现有查询。
独立于底层数据存储 API 工作。

Query by Example 也有几个局限性：

不支持嵌套或分组的属性约束，例如 firstname = ?0 或 (firstname = ?1 且 lastname = ?2)。
不支持匹配集合或映射。
字符串匹配的存储特定支持。根据你的数据库，字符串匹配可以支持字符串的开头/包含/结尾/正则表达式匹配。
其他属性类型的精确匹配。

在开始使用 Query by Example 之前，你需要有一个领域对象。要开始使用，请为你的存储库创建一个接口，如下例所示：

public class Person {

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

  // … getters and setters omitted
}
java

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

备注

在基于示例的查询（Query by Example）条件中，属性的包含与否基于其可空性。使用基本类型（如 int、double 等）的属性总是被包含，除非 ExampleMatcher 忽略了该属性路径。

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

示例 1. 简单示例

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

示例匹配器

示例不仅限于默认设置。你可以通过使用 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
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` 和属性路径
值转换	属性路径

Fluent API

QueryByExampleExecutor 还提供了一个我们之前没有提到的方法：<S extends T, R> R findBy(Example<S> example, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction)。与其他方法一样，它执行一个从 Example 派生的查询。然而，通过第二个参数，你可以控制查询执行的一些方面，这些方面在其他情况下无法动态控制。你可以通过调用第二个参数中的 FetchableFluentQuery 的各种方法来实现这一点。sortBy 允许你为结果指定排序方式。as 允许你指定希望将结果转换成的类型。project 限制查询的属性。first、firstValue、one、oneValue、all、page、stream、count 和 exists 定义了返回结果的类型，以及当结果数量超出预期时查询的行为。

Optional<Person> 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()。

Query By Example 在您不知道查询中需要哪些字段时表现得尤为出色。如果您正在构建一个网页过滤器，用户可以自行选择字段，那么 Query By Example 是一种灵活地将这些选择转化为高效查询的好方法。

引言​

用法​

示例匹配器​

Fluent API​

引言

用法

示例匹配器

Fluent API