示例查询

简介

本章介绍示例查询，并解释如何使用它。

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

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

用法

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

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

示例查询非常适合几种用例

使用一组静态或动态约束查询您的数据存储。
频繁重构域对象，而无需担心破坏现有查询。
独立于底层数据存储 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`和属性路径
值转换	属性路径

Fluent 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定义您获得的结果类型以及当结果数量超过预期数量时查询的行为。

使用Fluent 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()。

当您事先不知道查询所需的所有字段时，Query By Example 的优势就体现出来了。如果您正在构建一个网页上的过滤器，用户可以在其中选择字段，那么 Query By Example 是一种灵活地将这些字段捕获到高效查询中的好方法。