介绍

本章介绍示例查询，并说明如何使用它。Spring中文文档

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

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

用法

按示例查询 API 由四个部分组成：Spring中文文档

  • Probe：具有填充字段的域对象的实际示例。Spring中文文档

  • ExampleMatcher：包含有关如何匹配特定字段的详细信息。 它可以在多个示例中重复使用。ExampleMatcherSpring中文文档

  • Example： An 由探头和 . 它用于创建查询。ExampleExampleMatcherSpring中文文档

  • FetchableFluentQuery：A 提供了一个流畅的 API，允许进一步自定义派生自 . 使用 Fluent API，您可以为查询指定排序、投影和结果处理。FetchableFluentQueryExampleSpring中文文档

按示例查询非常适合以下几个用例：Spring中文文档

按示例查询还具有以下几个限制：Spring中文文档

  • 不支持嵌套或分组属性约束，例如 .firstname = ?0 or (firstname = ?1 and lastname = ?2)Spring中文文档

  • 特定于存储的字符串匹配支持。 根据数据库的不同，字符串匹配可以支持字符串的 starts/contains/ends/regex。Spring中文文档

  • 与其他属性类型完全匹配。Spring中文文档

在开始使用“按示例查询”之前，您需要有一个域对象。 若要开始，请为存储库创建一个接口，如以下示例所示：Spring中文文档

Sample Person 对象
public class Person {

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

  // … getters and setters omitted
}

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

将属性包含在“按示例查询”条件中是基于可为空性的。 除非 ExampleMatcher 忽略属性路径，否则始终包含使用基元类型 （， ， ...） 的属性。intdouble

可以使用工厂方法或使用 ExampleMatcher 生成示例。 是不可变的。 以下列表显示了一个简单的示例：ofExampleSpring中文文档

例 1.简单示例
Person person = new Person();                         (1)
person.setFirstname("Dave");                          (2)

Example<Person> example = Example.of(person);         (3)
1 创建域对象的新实例。
2 设置要查询的属性。
3 创建 .Example

您可以使用存储库运行示例查询。 为此，请让您的存储库接口扩展。 以下列表显示了该接口的摘录：QueryByExampleExecutor<T>QueryByExampleExecutorSpring中文文档

这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 忽略属性路径，否则始终包含使用基元类型 （， ， ...） 的属性。intdouble
1 创建域对象的新实例。
2 设置要查询的属性。
3 创建 .Example

示例匹配器

示例不限于默认设置。 可以使用 指定自己的字符串匹配、空处理和特定于属性的设置的默认值，如以下示例所示：ExampleMatcherSpring中文文档

例 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 构造一个新以忽略属性路径。ExampleMatcherlastname
5 构造一个新构造以忽略属性路径并包含 null 值。ExampleMatcherlastname
6 构造一个新构造以忽略属性路径、包含 null 值并执行后缀字符串匹配。ExampleMatcherlastname
7 根据域对象和配置的 .ExampleExampleMatcher

默认情况下，要求探测器上设置的所有值都匹配。 如果要获得与隐式定义的任何谓词匹配的结果，请使用 。ExampleMatcherExampleMatcher.matchingAny()Spring中文文档

您可以为单个属性（例如“firstname”和“lastname”或嵌套属性指定“address.city”）的行为。 您可以使用匹配选项和区分大小写来调整它，如以下示例所示：Spring中文文档

配置匹配器选项
ExampleMatcher matcher = ExampleMatcher.matching()
  .withMatcher("firstname", endsWith())
  .withMatcher("lastname", startsWith().ignoreCase());
}

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

使用 lambda 配置匹配器选项
ExampleMatcher matcher = ExampleMatcher.matching()
  .withMatcher("firstname", match -> match.endsWith())
  .withMatcher("firstname", match -> match.startsWith());
}

使用配置的合并视图创建的查询。 可以在级别设置默认匹配设置，而单个设置可以应用于特定的属性路径。 设置为“打开”的设置由属性路径设置继承，除非显式定义。 属性修补程序上的设置比默认设置具有更高的优先级。 下表描述了各种设置的范围：ExampleExampleMatcherExampleMatcherExampleMatcherSpring中文文档

表 1.设置范围ExampleMatcher
设置 范围

空处理Spring中文文档

ExampleMatcherSpring中文文档

字符串匹配Spring中文文档

ExampleMatcher和属性路径Spring中文文档

忽略属性Spring中文文档

属性路径Spring中文文档

区分大小写Spring中文文档

ExampleMatcher和属性路径Spring中文文档

价值转化Spring中文文档

属性路径Spring中文文档
1 创建域对象的新实例。
2 设置属性。
3 创建一个期望所有值都匹配的值。 即使没有进一步的配置，它也可以在这个阶段使用。ExampleMatcher
4 构造一个新以忽略属性路径。ExampleMatcherlastname
5 构造一个新构造以忽略属性路径并包含 null 值。ExampleMatcherlastname
6 构造一个新构造以忽略属性路径、包含 null 值并执行后缀字符串匹配。ExampleMatcherlastname
7 根据域对象和配置的 .ExampleExampleMatcher
表 1.设置范围ExampleMatcher
设置 范围

空处理Spring中文文档

ExampleMatcherSpring中文文档

字符串匹配Spring中文文档

ExampleMatcher和属性路径Spring中文文档

忽略属性Spring中文文档

属性路径Spring中文文档

区分大小写Spring中文文档

ExampleMatcher和属性路径Spring中文文档

价值转化Spring中文文档

属性路径Spring中文文档

Fluent API

QueryByExampleExecutor提供了另一种方法，到目前为止我们还没有提到：. 与其他方法一样，它执行派生自 . 但是，使用第二个参数，您可以控制该执行的方面，否则无法动态控制。 您可以通过调用第二个参数中的各种方法来执行此操作。 允许您指定结果的顺序。 允许您指定要将结果转换为的类型。 限制查询的属性。、 、 、<S extends T, R> R findBy(Example<S> example, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction)ExampleFetchableFluentQuerysortByasprojectfirstfirstValueoneoneValueallpagestreamcountexistsSpring中文文档

使用 Fluent API 获取可能众多结果中的最后一个，按姓氏排序。
Optional<Person> match = repository.findBy(example,
    q -> q
        .sortBy(Sort.by("lastname").descending())
        .first()
);

在 Spring Data JPA 中，您可以将 Query by Example 与存储库一起使用，如以下示例所示：Spring中文文档

例 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中文文档

下表显示了您可以使用的各种选项，以及在名为 ： 的字段上使用这些选项的结果：StringMatcherfirstnameSpring中文文档

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

DEFAULT（区分大小写）Spring中文文档

firstname = ?0Spring中文文档

DEFAULT（不区分大小写）Spring中文文档

LOWER(firstname) = LOWER(?0)Spring中文文档

EXACT（区分大小写）Spring中文文档

firstname = ?0Spring中文文档

EXACT（不区分大小写）Spring中文文档

LOWER(firstname) = LOWER(?0)Spring中文文档

STARTING（区分大小写）Spring中文文档

firstname like ?0 + '%'Spring中文文档

STARTING（不区分大小写）Spring中文文档

LOWER(firstname) like LOWER(?0) + '%'Spring中文文档

ENDING（区分大小写）Spring中文文档

firstname like '%' + ?0Spring中文文档

ENDING（不区分大小写）Spring中文文档

LOWER(firstname) like '%' + LOWER(?0)Spring中文文档

CONTAINING（区分大小写）Spring中文文档

firstname like '%' + ?0 + '%'Spring中文文档

CONTAINING（不区分大小写）Spring中文文档

LOWER(firstname) like '%' + LOWER(?0) + '%'Spring中文文档
JPA 不支持正则表达式匹配。
目前，只有属性可用于属性匹配。SingularAttribute
表 2. 选项StringMatcher
匹配 合乎逻辑的结果

DEFAULT（区分大小写）Spring中文文档

firstname = ?0Spring中文文档

DEFAULT（不区分大小写）Spring中文文档

LOWER(firstname) = LOWER(?0)Spring中文文档

EXACT（区分大小写）Spring中文文档

firstname = ?0Spring中文文档

EXACT（不区分大小写）Spring中文文档

LOWER(firstname) = LOWER(?0)Spring中文文档

STARTING（区分大小写）Spring中文文档

firstname like ?0 + '%'Spring中文文档

STARTING（不区分大小写）Spring中文文档

LOWER(firstname) like LOWER(?0) + '%'Spring中文文档

ENDING（区分大小写）Spring中文文档

firstname like '%' + ?0Spring中文文档

ENDING（不区分大小写）Spring中文文档

LOWER(firstname) like '%' + LOWER(?0)Spring中文文档

CONTAINING（区分大小写）Spring中文文档

firstname like '%' + ?0 + '%'Spring中文文档

CONTAINING（不区分大小写）Spring中文文档

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