按示例查询

介绍

本章介绍了按示例查询（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)。
不支持匹配集合或映射。
特定于存储的字符串匹配支持。根据您的数据库，字符串匹配可能支持字符串的 starts/contains/ends/regex。
对其他属性类型进行精确匹配。

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

人员对象示例

public class Person {

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

  // … getters and setters omitted
}

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

将属性包含到按示例查询标准中是基于可为 null 性的。使用原始类型（int, double, …）的属性总是被包含，除非 ExampleMatcher 忽略了该属性路径。

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

示例 1. 简单示例

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

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

1	创建一个领域对象的新实例。
2	设置要查询的属性。
3	创建 `Example`。

您可以使用 repositories 运行示例查询。为此，让您的 repository 接口继承 QueryByExampleExecutor<T>。以下清单显示了 QueryByExampleExecutor 接口的片段

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

示例匹配器

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

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

1	创建一个领域对象的新实例。
2	设置属性。
3	创建一个 `ExampleMatcher`，期望所有值都匹配。即使没有进一步配置，它在此阶段也是可用的。
4	构造一个新的 `ExampleMatcher` 来忽略 `lastname` 属性路径。
5	构造一个新的 `ExampleMatcher` 来忽略 `lastname` 属性路径并包含 null 值。
6	构造一个新的 `ExampleMatcher` 来忽略 `lastname` 属性路径，包含 null 值，并执行后缀字符串匹配。
7	根据领域对象和配置的 `ExampleMatcher` 创建一个新的 `Example`。

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

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

配置匹配器选项

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

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

使用 lambdas 配置匹配器选项

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

Example 创建的查询使用了配置的合并视图。默认匹配设置可以在 ExampleMatcher 级别设置，而单个设置可以应用于特定的属性路径。在 ExampleMatcher 上设置的设置会被属性路径设置继承，除非它们被明确定义。属性路径上的设置优先于默认设置。下表描述了各种 ExampleMatcher 设置的作用域

表 1. `ExampleMatcher` 设置的作用域
设置	作用域
Null 处理	`ExampleMatcher`
字符串匹配	`ExampleMatcher` 和属性路径
忽略属性	属性路径
大小写敏感性	`ExampleMatcher` 和属性路径
值转换	属性路径

流畅 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 定义您获得的结果类型以及当结果数量超出预期时查询的行为。

使用流畅 API 获取潜在的多个结果中的最后一个，按 lastname 排序。

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

在 Spring Data JPA 中，您可以将按示例查询与 Repositories 一起使用，如下例所示

示例 3. 使用 Repository 的按示例查询

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

目前，只有 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 不支持正则表达式匹配。