按示例查询

简介

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

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

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

用法

Query by Example API 由四个部分组成

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

Query by Example 非常适合几种用例

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

示例查询也有一些限制

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

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

示例 Person 对象

public class Person {

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

  // … getters and setters omitted
}

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

将属性包含到示例查询条件中是基于可空性的。使用基本类型（int、double 等）的属性始终包含在内，除非 ExampleMatcher 忽略属性路径。

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

示例 1. 简单示例

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

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

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

您可以使用存储库运行示例查询。为此，让您的存储库接口扩展 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.
}

示例匹配器

示例不限于默认设置。您可以使用 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)

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

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

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

配置匹配器选项

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

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

使用 lambda 配置匹配器选项

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

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

表 1. `ExampleMatcher` 设置的范围
设置	范围
空值处理	`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	通过存储库，执行查询（对于单个项目，使用 `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

1	创建一个自定义的 `ExampleMatcher`，它匹配所有字段（使用 `matchingAny()` 匹配任何字段）。
2	对于 `name` 字段，使用一个通配符，它匹配字段的末尾。
3	将列与 `null` 进行匹配（不要忘记，在关系型数据库中，`NULL` 不等于 `NULL`）。
4	在形成查询时忽略 `role` 字段。
5	将自定义的 `ExampleMatcher` 插入探测器。

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

当你事先不知道查询中需要的所有字段时，示例查询非常有用。如果你正在构建一个网页上的过滤器，用户可以在其中选择字段，示例查询是一种灵活地将这些字段捕获到高效查询中的好方法。