此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Data JPA 3.4.0！spring-doc.cn

按示例查询

介绍

本章介绍了 Query by Example 并说明了如何使用它。spring-doc.cn

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

本章介绍了 Query by Example 的核心概念。该信息是从 Spring Data Commons 模块中提取的。根据您的数据库，字符串匹配支持可能会受到限制。

用法

Query by Example API 由四个部分组成：spring-doc.cn

探测：具有填充字段的域对象的实际示例。spring-doc.cn
ExampleMatcher：包含有关如何匹配特定字段的详细信息。它可以在多个 Example 中重复使用。ExampleMatcherspring-doc.cn
Example：An 由探针和 . 它用于创建查询。ExampleExampleMatcherspring-doc.cn
FetchableFluentQuery：A 提供 Fluent API，允许进一步自定义从 . 使用 Fluent API 可以为查询指定排序、投影和结果处理。FetchableFluentQueryExamplespring-doc.cn

Query by Example 非常适合以下几种使用案例：spring-doc.cn

使用一组静态或动态约束查询数据存储。spring-doc.cn
频繁重构域对象，而无需担心中断现有查询。spring-doc.cn
独立于底层数据存储 API 工作。spring-doc.cn

Query by Example 也有几个限制：spring-doc.cn

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

在开始使用 Query by Example 之前，您需要有一个域对象。要开始使用，请为您的仓库创建一个界面，如以下示例所示：spring-doc.cn

Sample Person 对象

public class Person {

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

  // … getters and setters omitted
}

前面的示例显示了一个简单的域对象。您可以使用它来创建一个 . 默认情况下，将忽略具有值的字段，并使用特定于存储的默认值来匹配字符串。Examplenullspring-doc.cn

将属性包含在 Query by Example 条件中基于可为 null 性。除非 ExampleMatcher 忽略属性路径，否则始终包含使用原始类型（，， ...）的属性。intdouble

可以使用 factory 方法或使用 ExampleMatcher 来构建示例。是不可变的。下面的清单显示了一个简单的示例：ofExamplespring-doc.cn

示例 1.简单示例

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

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

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

您可以使用存储库运行示例查询。为此，请让您的存储库接口 extend 。下面的清单显示了该界面的摘录：QueryByExampleExecutor<T>QueryByExampleExecutorspring-doc.cn

这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.
}

示例 Matchers

示例不限于默认设置。您可以使用为字符串匹配、null 处理和特定于属性的设置指定自己的默认值，如以下示例所示：ExampleMatcherspring-doc.cn

示例 2.具有自定义匹配的示例 matcher

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	创建 domain 对象的新实例。
2	设置属性。
3	创建一个预期所有值都匹配的 URL。即使无需进一步配置，它也可以在此阶段使用。`ExampleMatcher`
4	构造一个 new 以忽略属性路径。`ExampleMatcherlastname`
5	构造一个 new 以忽略属性路径并包含 null 值。`ExampleMatcherlastname`
6	构造一个 new 以忽略属性路径、包含 null 值并执行后缀字符串匹配。`ExampleMatcherlastname`
7	根据域对象和配置的 .`ExampleExampleMatcher`

默认情况下，期望探测器上设置的所有值都匹配。如果要获得与隐式定义的任何谓词匹配的结果，请使用 .ExampleMatcherExampleMatcher.matchingAny()spring-doc.cn

您可以为各个属性指定行为（例如“firstname”和“lastname”，或者对于嵌套属性，则为“address.city”）。您可以使用匹配选项和区分大小写对其进行优化，如以下示例所示：spring-doc.cn

配置 matcher 选项

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

配置 matcher 选项的另一种方法是使用 lambdas（在 Java 8 中引入）。此方法创建一个回调，要求实现者修改匹配器。您无需返回 matcher，因为 configuration 选项保存在 matcher 实例中。以下示例显示了使用 lambda 的匹配程序：spring-doc.cn

使用 lambda 配置 matcher 选项

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

创建的查询使用配置的合并视图。可以在级别设置默认匹配设置，而单个设置可以应用于特定属性路径。设置为 on 的设置将由属性路径设置继承，除非它们被明确定义。属性 Patch 上的设置的优先级高于默认设置。下表描述了各种设置的范围：ExampleExampleMatcherExampleMatcherExampleMatcherspring-doc.cn

表 1.设置范围`ExampleMatcher`
设置	范围
Null 处理spring-doc.cn	`ExampleMatcher`spring-doc.cn
字符串匹配spring-doc.cn	`ExampleMatcher`和属性路径spring-doc.cn
忽略属性spring-doc.cn	属性路径spring-doc.cn
区分大小写spring-doc.cn	`ExampleMatcher`和属性路径spring-doc.cn
价值转型spring-doc.cn	属性路径spring-doc.cn

Fluent API

QueryByExampleExecutor提供了另一种方法，到目前为止我们没有提到：。与其他方法一样，它执行从 . 但是，使用第二个参数，您可以控制该执行的方面，否则您将无法动态控制这些方面。您可以通过调用第二个参数中 the 的各种方法来执行此操作。用于指定结果的顺序。用于指定要将结果转换为的类型。限制查询的属性。、、、、、、，并定义您获得的结果类型以及当可用结果数超过预期数量时查询的行为方式。<S extends T, R> R findBy(Example<S> example, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction)ExampleFetchableFluentQuerysortByasprojectfirstfirstValueoneoneValueallpagestreamcountexistsspring-doc.cn

使用 Fluent API 获取可能许多结果中的最后一个结果，按 lastname 排序。

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

在 Spring Data JPA 中，您可以将 Query by Example 与 Repositories 一起使用，如以下示例所示：spring-doc.cn

例 3.使用存储库按示例查询

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

属性说明符接受属性名称（如和）。您可以通过使用点（）将属性链接在一起来导航。您还可以使用匹配选项和区分大小写来调整它。firstnamelastnameaddress.cityspring-doc.cn

下表显示了您可以使用的各种选项，以及在名为的字段上使用这些选项的结果：StringMatcherfirstnamespring-doc.cn

表 2. 选项`StringMatcher`
匹配	逻辑结果
`DEFAULT`（区分大小写）spring-doc.cn	`firstname = ?0`spring-doc.cn
`DEFAULT`（不区分大小写）spring-doc.cn	`LOWER(firstname) = LOWER(?0)`spring-doc.cn
`EXACT`（区分大小写）spring-doc.cn	`firstname = ?0`spring-doc.cn
`EXACT`（不区分大小写）spring-doc.cn	`LOWER(firstname) = LOWER(?0)`spring-doc.cn
`STARTING`（区分大小写）spring-doc.cn	`firstname like ?0 + '%'`spring-doc.cn
`STARTING`（不区分大小写）spring-doc.cn	`LOWER(firstname) like LOWER(?0) + '%'`spring-doc.cn
`ENDING`（区分大小写）spring-doc.cn	`firstname like '%' + ?0`spring-doc.cn
`ENDING`（不区分大小写）spring-doc.cn	`LOWER(firstname) like '%' + LOWER(?0)`spring-doc.cn
`CONTAINING`（区分大小写）spring-doc.cn	`firstname like '%' + ?0 + '%'`spring-doc.cn
`CONTAINING`（不区分大小写）spring-doc.cn	`LOWER(firstname) like '%' + LOWER(?0) + '%'`spring-doc.cn

JPA 不支持正则表达式匹配。