文档内容来源于 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 模块。根据你所使用的数据库，字符串匹配的支持可能会受到限制。

用法

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

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

按示例查询（Query by Example）非常适用于以下几种用例：

使用一组静态或动态约束条件查询您的数据存储。
在不担心破坏现有查询的情况下，频繁重构领域对象。
独立于底层数据存储 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 是不可变的。以下清单展示了一个简单的 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 期望探针（probe）上设置的所有值都匹配。如果你想获取与隐式定义的任一谓词（predicate）匹配的结果，请使用 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

在 Spring Data JPA 中，你可以使用基于示例的查询（Query by Example）与仓库（Repositories），如下例所示：

示例 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));
  }
}
java

备注

目前，只有 SingularAttribute 属性可以用于属性匹配。

属性指定器接受属性名称（例如 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 不支持正则表达式匹配。

引言​

用法​

示例匹配器​

Fluent API​

引言

用法

示例匹配器

Fluent API