按示例查询

简介

本章介绍按示例查询，并说明如何使用。

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

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

用法

按示例查询 API 由四部分组成

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

按示例查询非常适合多种用例

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

按示例查询还有一些限制

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

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

示例人员对象

public class Person {

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

  // … getters and setters omitted
}

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

将属性包含到按示例查询标准中基于可空性。使用原始类型（int、double、…）的属性始终包含在内，除非示例匹配器忽略属性路径。

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

示例 1. 简单示例

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

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

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

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

示例匹配器

示例不限于默认设置。你可以使用示例匹配器指定字符串匹配、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` 属性路径并包含空值。
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()
);