范例查询

简介

本章介绍 Query by Example 并解释如何使用它。

Query by Example (QBE) 是一种用户友好的查询技术，具有简单的接口。它允许动态创建查询，并且不需要编写包含字段名的查询。实际上，Query by Example 完全不需要使用特定于存储的查询语言来编写查询。

本章解释了 Query by Example 的核心概念。这些信息来自 Spring Data Commons 模块。根据您的数据库，字符串匹配支持可能有限。

用法

Query by Example API 由四部分组成

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

Query by Example 非常适合以下几个用例

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

Query by Example 也有一些限制

不支持嵌套或分组的属性约束，例如 firstname = ?0 or (firstname = ?1 and lastname = ?2)。
不支持匹配集合或映射。
特定于存储的字符串匹配支持。根据您的数据库，字符串匹配可以支持 starts/contains/ends/regex。
其他属性类型的精确匹配。

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

Person 对象示例

public class Person {

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

  // … getters and setters omitted
}

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

属性是否包含在 Query by Example 条件中取决于其可空性。除非 ExampleMatcher 忽略该属性路径，否则原始类型（int, double, …）的属性总是被包含。

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

例 1. 简单 Example

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

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

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

您可以使用 repositories 运行 example 查询。为此，让您的 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 Matcher

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

例 2. 使用自定义匹配的 Example matcher

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 期望 probe 上设置的所有值都匹配。如果您想获得匹配任何隐式定义的谓词的结果，请使用 ExampleMatcher.matchingAny()。

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

配置 matcher 选项

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

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

使用 lambdas 配置 matcher 选项

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

这里有一个示例

Employee employee = new Employee(); (1)
employee.name= "Frodo";

Example<Employee> example = Example.of(employee); (2)

repository.findAll(example); (3)

// do whatever with the result

1	创建带有条件的领域对象（`null` 字段将被忽略）。
2	使用领域对象创建 `Example`。
3	通过 repository 执行查询（对于单个项目使用 `findOne`）。

这说明了如何使用领域对象构建一个简单的 probe。在本例中，它将基于 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

1	创建一个自定义的 `ExampleMatcher`，它匹配所有字段（使用 `matchingAny()` 匹配任意字段）。
2	对于 `name` 字段，使用一个通配符匹配字段的末尾。
3	匹配列是否为 `null`（别忘了在关系型数据库中 `NULL` 不等于 `NULL`）。
4	在形成查询时忽略 `role` 字段。
5	将自定义的 `ExampleMatcher` 插入到 probe 中。

还可以对任何属性应用 withTransform()，允许您在形成查询之前转换属性。例如，您可以在创建查询之前对基于 String 的属性应用 toUpperCase()。

当您不知道查询中需要的所有字段时，Query By Example 真正发挥作用。如果您正在构建一个网页上的过滤器，用户可以选择字段，那么 Query By Example 是将这些灵活地捕获到高效查询中的绝佳方法。