按示例查询

简介

本章介绍了按示例查询（Query by Example）并解释了如何使用它。

按示例查询（QBE）是一种用户友好的查询技术，接口简单。它允许动态创建查询，并且不需要您编写包含字段名的查询。事实上，按示例查询根本不需要您使用特定于存储的查询语言来编写查询。

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

用法

按示例查询 API 包含四个部分

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

按示例查询非常适合以下几种用例

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

按示例查询也存在一些限制

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

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

示例 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。Example 是不可变的。以下清单展示了一个简单的 Example

示例 1. 简单示例

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

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

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

您可以使用 Repository 来运行示例查询。为此，让您的 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 指定您自己的字符串匹配、空值处理和特定属性设置的默认值，如以下示例所示

示例 2. 自定义匹配的 Example 匹配器

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

另一种配置匹配器选项的方法是使用 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` 设置的作用范围
设置	作用范围
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 获取可能存在多个结果中的最后一个结果，并按姓氏排序。

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