示例查询

引言

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

示例查询 (QBE) 是一种用户友好的查询技术，界面简单。它允许动态创建查询，并且不需要你编写包含字段名称的查询。实际上，示例查询根本不需要你使用存储特定的查询语言来编写查询。

本章解释了示例查询的核心概念。这些信息提取自 Spring Data Commons 模块。根据你的数据库，字符串匹配支持可能会受到限制。

用法

Query by Example 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。
其他属性类型的精确匹配。

在开始使用 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 条件中是基于 nullability 的。原始类型的属性（int, double 等）总是包含在内，除非 ExampleMatcher 忽略了该属性路径。

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 运行示例查询。为此，让你的 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 Matchers

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 期望探针上设置的所有值都匹配。如果你想获取与隐式定义的任何谓词匹配的结果，请使用 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 级别设置，而 individual settings 可以应用于特定的属性路径。在 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()
);