|
此版本仍在开发中，尚不被认为是稳定的。对于最新的稳定版本，请使用 Spring Data Relational 3.5.2！ |
按示例查询
介绍
本章介绍了示例查询，并说明了如何使用它。
示例查询 （QBE） 是一种用户友好的查询技术，界面简单。 它允许动态查询创建，并且不需要您编写包含字段名称的查询。 事实上，Query by Example 根本不需要您使用特定于 store 的查询语言编写查询。
| 本章解释了“示例查询”的核心概念。 该信息是从 Spring Data Commons 模块中提取的。 根据数据库的不同，字符串匹配支持可能会受到限制。 |
用法
按示例查询 API 由四个部分组成：
-
探测：具有填充字段的域对象的实际示例。
-
ExampleMatcher：这ExampleMatcher包含有关如何匹配特定字段的详细信息。 它可以在多个示例中重用。 -
Example：一Example由探头和ExampleMatcher. 它用于创建查询。 -
FetchableFluentQuery：一个FetchableFluentQuery提供了一个流畅的 API，允许进一步自定义从Example. 使用 Fluent API 可以指定查询的排序、投影和结果处理。
按示例查询非常适合多种用例：
-
使用一组静态或动态约束查询数据存储。
-
频繁重构域对象，而不必担心破坏现有查询。
-
独立于基础数据存储 API 工作。
按示例查询也有几个限制：
-
不支持嵌套或分组属性约束，例如
firstname = ?0 or (firstname = ?1 and lastname = ?2). -
不支持匹配集合或地图。
-
对字符串匹配的特定于商店的支持。 根据您的数据库，字符串匹配可以支持字符串的开始/包含/结束/正则表达式。
-
与其他属性类型完全匹配。
在开始使用“按示例查询”之前，您需要有一个域对象。 若要开始，请为存储库创建一个接口，如以下示例所示：
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忽略属性路径. |
可以使用offactory 方法或使用ExampleMatcher.Example是不可变的。
以下列表显示了一个简单的示例：
Person person = new Person(); (1)
person.setFirstname("Dave"); (2)
Example<Person> example = Example.of(person); (3)| 1 | 创建域对象的新实例。 |
| 2 | 设置要查询的属性。 |
| 3 | 创建Example. |
可以使用存储库运行示例查询。
为此，请让您的存储库接口扩展QueryByExampleExecutor<T>.
以下列表显示了QueryByExampleExecutor接口：
QueryByExampleExecutorpublic interface QueryByExampleExecutor<T> {
<S extends T> S findOne(Example<S> example);
<S extends T> Iterable<S> findAll(Example<S> example);
// … more functionality omitted.
}示例匹配器
示例不限于默认设置。
您可以使用ExampleMatcher，如以下示例所示：
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 | 创建一个新的Example基于域对象和配置的ExampleMatcher. |
默认情况下，ExampleMatcher期望在探头上设置的所有值都匹配。
如果要获得与隐式定义的任何谓词匹配的结果，请使用ExampleMatcher.matchingAny().
您可以为单个属性指定行为（例如“firstname”和“lastname”，或者对于嵌套属性，“address.city”）。 可以使用匹配选项和区分大小写来调整它，如以下示例所示：
ExampleMatcher matcher = ExampleMatcher.matching()
.withMatcher("firstname", endsWith())
.withMatcher("lastname", startsWith().ignoreCase());
}配置匹配器选项的另一种方法是使用 lambda（在 Java 8 中引入）。 此方法创建一个回调，要求实现者修改匹配器。 您无需返回匹配器，因为配置选项保存在匹配器实例中。 以下示例显示了使用 lambda 的匹配器：
ExampleMatcher matcher = ExampleMatcher.matching()
.withMatcher("firstname", match -> match.endsWith())
.withMatcher("firstname", match -> match.startsWith());
}创建的查询Example使用配置的合并视图。
默认匹配设置可以在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,slice,stream,count和exists定义您获得的结果类型以及当可用结果超过预期数量时查询的行为方式。
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()针对任何属性，允许您在形成查询之前转换属性。
例如，您可以应用toUpperCase()设置为String-based 属性。
当您事先不知道查询中所需的所有字段时，Query By Example 确实会大放异彩。 如果您在用户可以选择字段的网页上构建过滤器，那么“按示例查询”是将其灵活捕获到高效查询中的好方法。