按示例查询

简介

本章介绍了 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 获取可能存在的多个结果中的最后一个结果，按姓氏排序。
Optional<Person> match = repository.findBy(example,
    q -> q
        .sortBy(Sort.by("lastname").descending())
        .first()
);

在 Spring Data JPA 中，您可以将 Query by Example 与 Repositories 一起使用，如下面的示例所示

示例 3. 使用 Repository 的 Query by Example
public interface PersonRepository extends JpaRepository<Person, String> { … }

public class PersonService {

  @Autowired PersonRepository personRepository;

  public List<Person> findPeople(Person probe) {
    return personRepository.findAll(Example.of(probe));
  }
}
目前，只有 SingularAttribute 属性可以用于属性匹配。

属性说明符接受属性名称（例如 firstname 和 lastname）。您可以通过将属性与点连接在一起（address.city）来导航。您还可以使用匹配选项和区分大小写来调整它。

下表显示了您可以使用的各种 StringMatcher 选项以及在名为 firstname 的字段上使用它们的結果

表 2. StringMatcher 选项
匹配 逻辑结果

DEFAULT（区分大小写）

firstname = ?0

DEFAULT（不区分大小写）

LOWER(firstname) = LOWER(?0)

EXACT（区分大小写）

firstname = ?0

EXACT（不区分大小写）

LOWER(firstname) = LOWER(?0)

STARTING（区分大小写）

firstname like ?0 + '%'

STARTING（不区分大小写）

LOWER(firstname) like LOWER(?0) + '%'

以...结尾 (区分大小写)

firstname like '%' + ?0

以...结尾 (不区分大小写)

LOWER(firstname) like '%' + LOWER(?0)

包含... (区分大小写)

firstname like '%' + ?0 + '%'

包含... (不区分大小写)

LOWER(firstname) like '%' + LOWER(?0) + '%'
JPA 不支持正则表达式匹配。