定义查询方法
仓库代理有两种方式从方法名派生特定于存储的查询:
- 通过直接从方法名派生查询。
- 通过使用手动定义的查询。
可用的选项取决于实际的存储。但是,必须有一个策略来决定创建什么样的实际查询。下一节介绍可用的选项。
查询查找策略
仓库基础设施可使用以下策略来解析查询。对于 XML 配置,你可以通过命名空间上的 query-lookup-strategy 属性来配置策略。对于 Java 配置,你可以使用 EnableRedisRepositories 注解的 queryLookupStrategy 属性。某些策略可能对特定数据存储不受支持。
CREATE尝试从查询方法名构造特定于存储的查询。一般方法是从方法名中移除一组已知的前缀,并解析方法的其余部分。你可以在“查询创建”中阅读更多关于查询构造的内容。USE_DECLARED_QUERY尝试找到一个已声明的查询,如果找不到则抛出异常。查询可以通过某处的注解定义,或通过其他方式声明。请参阅特定存储的文档,了解该存储可用的选项。如果仓库基础设施在引导时找不到该方法的已声明查询,它就会失败。CREATE_IF_NOT_FOUND(默认)组合了CREATE和USE_DECLARED_QUERY。它先查找已声明的查询,如果未找到已声明的查询,则创建一个基于自定义方法名的查询。这是默认的查找策略,因此如果你不显式配置任何内容,就会使用它。它允许通过方法名快速定义查询,也可以根据需要引入已声明的查询来对这些查询进行自定义调整。
查询创建
内置于 Spring Data 仓库基础设施中的查询构建器机制,可用于对仓库的实体构建约束查询。
以下示例展示了如何创建一些查询:
interface PersonRepository extends Repository<Person, Long> {
List<Person> findByEmailAddressAndLastname(EmailAddress emailAddress, String lastname);
// Enables the distinct flag for the query
List<Person> findDistinctPeopleByLastnameOrFirstname(String lastname, String firstname);
List<Person> findPeopleDistinctByLastnameOrFirstname(String lastname, String firstname);
// Enabling ignoring case for an individual property
List<Person> findByLastnameIgnoreCase(String lastname);
// Enabling ignoring case for all suitable properties
List<Person> findByLastnameAndFirstnameAllIgnoreCase(String lastname, String firstname);
// Enabling static ORDER BY for a query
List<Person> findByLastnameOrderByFirstnameAsc(String lastname);
List<Person> findByLastnameOrderByFirstnameDesc(String lastname);
}
解析查询方法名分为主语和谓词两部分。第一部分(find…By、exists…By)定义查询的主语,第二部分构成谓词。引导子句(主语)可以包含更多表达式。find(或其他引导关键字)与 By 之间的任何文本都被视为描述性的,除非使用某个结果限制关键字,例如 Distinct 为要创建的查询设置去重标志,或用 Top/First 限制查询结果。
附录包含查询方法主语关键字的完整列表以及查询方法谓词关键字(包括排序和大小写修饰符)。但是,第一个 By 充当分隔符,指示实际条件谓词的开始。在最基本的层面上,你可以对实体属性定义条件,并用 And 和 Or 连接它们。
解析方法的实际结果取决于你为之创建查询的持久化存储。但是,有一些通用的注意事项:
- 这些表达式通常是属性遍历,并结合可连接的运算符。你可以用
AND和OR组合属性表达式。你还可以为属性表达式使用诸如Between、LessThan、GreaterThan和Like之类的运算符。支持的运算符可能因数据存储而异,因此请参阅参考文档的相应部分。 - 方法解析器支持为单个属性设置
IgnoreCase标志(例如findByLastnameIgnoreCase(…)),或为支持忽略大小写的类型的所有属性设置(通常是String实例——例如findByLastnameAndFirstnameAllIgnoreCase(…))。是否支持忽略大小写可能因存储而异,因此请参阅参考文档中关于特定存储查询方法的相关章节。 - 你可以通过在查询方法后追加一个引用某属性的
OrderBy子句并提供排序方向(Asc或Desc)来应用静态排序。要创建支持动态排序的查询方法,请参阅“分页、迭代大型结果、排序与限制”。
保留方法名
虽然派生的仓库方法按名称绑定到属性,但在从基础仓库继承的、针对_标识符_属性的某些方法名上,这条规则有一些例外。那些_保留方法_,如 CrudRepository#findById(或直接 findById),针对的是_标识符_属性,而不管声明的方法中使用的实际属性名是什么。
考虑下面这个领域类型,它有一个通过 @Id 标记为标识符的属性 pk,以及一个名为 id 的属性。在这种情况下,你需要密切注意查找方法的命名,因为它们可能与预定义的签名冲突:
class User {
@Id Long pk; 1
Long id; 2
// …
}
interface UserRepository extends Repository<User, Long> {
Optional<User> findById(Long id); 3
Optional<User> findByPk(Long pk); 4
Optional<User> findUserById(Long id); 5
}
标识符属性(主键)。
一个名为
id的属性,但不是标识符。针对
pk属性(用@Id标记、被视为标识符的那个),因为它指向一个CrudRepository基础仓库方法。因此,它并不是一个以id作为属性名的派生查询所暗示的那样,因为它是_保留方法_之一。通过名称针对
pk属性,因为它是一个派生查询。通过使用
find与by之间的描述性标记,针对id属性,以避免与_保留方法_冲突。
这种特殊行为不仅针对查找方法,也适用于 exists 和 delete 方法。方法列表请参阅“仓库查询关键字”。
属性表达式
属性表达式只能引用所管理实体的直接属性,如前面的示例所示。在查询创建时,你已经确保解析出的属性是所管理领域类的属性。但是,你也可以通过遍历嵌套属性来定义约束。考虑下面这个方法签名:
List<Person> findByAddressZipCode(ZipCode zipCode);
假设一个 Person 有一个带 ZipCode 的 Address。在这种情况下,该方法会创建 x.address.zipCode 属性遍历。解析算法首先将整个部分(AddressZipCode)解释为属性,并在领域类中检查是否有该名称(首字母小写)的属性。如果算法成功,就使用该属性。如果不成功,算法会从右侧将驼峰式部分拆分为头部和尾部,并尝试找到相应的属性——在我们的示例中是 AddressZip 和 Code。如果算法找到具有该头部的属性,它就取尾部并从那里继续向下构建树,按刚才描述的方式拆分尾部。如果第一次拆分不匹配,算法就把拆分点移到左侧(Address、ZipCode)并继续。
虽然这对大多数情况应该有效,但算法也有可能选错属性。假设 Person 类还有一个 addressZip 属性。算法在第一轮拆分中就会匹配,选错属性并失败(因为 addressZip 的类型很可能没有 code 属性)。
为了解决这种歧义,你可以在方法名中使用 _ 来手动定义遍历点。因此我们的方法名将如下所示:
List<Person> findByAddress_ZipCode(ZipCode zipCode);
由于我们将下划线(_)视为保留字符,我们强烈建议遵循标准的 Java 命名约定(也就是说,不要在属性名中使用下划线,而是使用驼峰命名法)。
以下划线开头的字段名:
字段名可以以下划线开头,例如 String _name。请确保保留 _,如 _name 中那样,并使用双下划线 __ 来拆分嵌套路径,例如 user__name。
大写字段名:
全大写的字段名可以原样使用。嵌套路径(如果适用)需要通过 _ 拆分,如 USER_name。
第二个字母大写的字段名:
由一个小写字母开头、后接一个大写字母组成的字段名,例如 String qCode,可以通过以两个大写字母开头来解析,如 QCode。请注意潜在的路径歧义。
路径歧义:
在下面的示例中,属性 qCode 和 q 的排列(其中 q 包含一个名为 code 的属性)为路径 QCode 造成了歧义。
record Container(String qCode, Code q) {}
record Code(String code) {}
由于会优先考虑对属性的直接匹配,因此不会考虑任何潜在的嵌套路径,算法会选择 qCode 字段。为了选择 q 中的 code 字段,需要使用下划线表示法 Q_Code。
返回集合或可迭代对象的仓库方法
使用 Streamable 作为查询方法返回类型
你可以使用 Streamable 作为 Iterable 或任何集合类型的替代。它提供了便捷方法来访问非并行的 Stream(Iterable 中所缺少的),以及直接对元素进行 ….filter(…) 和 ….map(…) 并将 Streamable 连接到其他对象的能力:
interface PersonRepository extends Repository<Person, Long> {
Streamable<Person> findByFirstnameContaining(String firstname);
Streamable<Person> findByLastnameContaining(String lastname);
}
Streamable<Person> result = repository.findByFirstnameContaining("av")
.and(repository.findByLastnameContaining("ea"));
返回自定义 Streamable 包装类型
为集合提供专用的包装类型是一种常用模式,用于为返回多个元素的查询结果提供 API。通常,这些类型的使用方式是调用一个返回类集合类型的仓库方法,然后手动创建该包装类型的实例。你可以省去这一额外步骤,因为如果这些包装类型满足以下条件,Spring Data 允许你将它们用作查询方法的返回类型:
- 该类型实现
Streamable。 - 该类型暴露一个构造函数,或一个名为
of(…)或valueOf(…)的静态工厂方法,该方法接受Streamable作为参数。
以下列表展示了一个示例:
class Product { 1
MonetaryAmount getPrice() { … }
}
@RequiredArgsConstructor(staticName = "of")
class Products implements Streamable<Product> { 2
private final Streamable<Product> streamable;
public MonetaryAmount getTotal() { 3
return streamable.stream()
.map(Product::getPrice)
.reduce(Money.of(0), MonetaryAmount::add);
}
@Override
public Iterator<Product> iterator() { 4
return streamable.iterator();
}
}
interface ProductRepository extends Repository<Product, Long> {
Products findAllByDescriptionContaining(String text); 5
}
一个
Product实体,暴露访问产品价格的 API。一个
Streamable<Product>的包装类型,可以通过使用Products.of(…)(用 Lombok 注解创建的工厂方法)来构造。接受Streamable<Product>的标准构造函数也可以。该包装类型暴露一个额外的 API,在
Streamable<Product>上计算新值。实现
Streamable接口并委托给实际结果。该包装类型
Products可以直接用作查询方法返回类型。你不需要返回Streamable<Product>并在仓库客户端的查询之后手动包装它。
对 Vavr 集合的支持
Vavr 是一个在 Java 中拥抱函数式编程概念的库。它附带一套自定义的集合类型,你可以将其用作查询方法返回类型,如下表所示:
| Vavr 集合类型 | 使用的 Vavr 实现类型 | 有效的 Java 源类型 |
|---|---|---|
io.vavr.collection.Seq | io.vavr.collection.List | java.util.Iterable |
io.vavr.collection.Set | io.vavr.collection.LinkedHashSet | java.util.Iterable |
io.vavr.collection.Map | io.vavr.collection.LinkedHashMap | java.util.Map |
你可以使用第一列中的类型(或其子类型)作为查询方法返回类型,并根据实际查询结果的 Java 类型(第三列)使用第二列中的类型作为实现类型。或者,你可以声明 Traversable(Vavr 的 Iterable 等效物),然后我们从实际返回值派生出实现类。也就是说,java.util.List 会被转换为 Vavr 的 List 或 Seq,java.util.Set 会变成 Vavr 的 LinkedHashSet Set,依此类推。
流式传输查询结果
你可以使用 Stream<T> 作为返回类型来增量处理查询方法的结果。数据存储特定的方法用于执行流式传输,而不是将查询结果包装在 Stream 中,如下例所示:
@Query("select u from User u")
Stream<User> findAllByCustomQueryAndStream();
Stream<User> readAllByFirstnameNotNull();
@Query("select u from User u")
Stream<User> streamAllPaged(Pageable pageable);
一个 Stream 可能包装了底层数据存储特定的资源,因此使用后必须关闭它。你可以使用 close() 方法手动关闭 Stream,或者使用 try-with-resources 块,如下例所示:
try (Stream<User> stream = repository.findAllByCustomQueryAndStream()) {
stream.forEach(…);
}
并非所有 Spring Data 模块目前都支持 Stream<T> 作为返回类型。
异步查询结果
你可以使用 Spring 的异步方法运行能力来异步运行仓库查询。这意味着方法在调用时立即返回,而实际查询发生在一个已提交给 Spring TaskExecutor 的任务中。异步查询与响应式查询不同,不应混用。有关响应式支持的更多详情,请参阅特定于存储的文档。以下示例展示了一些异步查询:
@Async
Future<User> findByFirstname(String firstname); 1
@Async
CompletableFuture<User> findOneByFirstname(String firstname); 2
使用
java.util.concurrent.Future作为返回类型。使用
java.util.concurrent.CompletableFuture作为返回类型。
分页、迭代大型结果、排序与限制
要处理查询中的参数,请像前面示例中那样定义方法参数。除此之外,基础设施还会识别某些特定类型,如 Pageable、Sort 和 Limit,以动态地对查询应用分页、排序和限制。以下示例演示了这些功能:
Page<User> findByLastname(String lastname, Pageable pageable);
Slice<User> findByLastname(String lastname, Pageable pageable);
List<User> findByLastname(String lastname, Sort sort);
List<User> findByLastname(String lastname, Sort sort, Limit limit);
List<User> findByLastname(String lastname, Pageable pageable);
接受 Sort、Pageable 和 Limit 的 API 期望向方法传递非 null 值。如果你不想应用任何排序或分页,请使用 Sort.unsorted()、Pageable.unpaged() 和 Limit.unlimited()。
第一个方法让你向查询方法传递一个 org.springframework.data.domain.Pageable 实例,以动态地为你静态定义的查询添加分页。Page 知道元素和可用页面的总数。它是通过基础设施触发一个 count 查询来计算总数的。由于这可能代价高昂(取决于所使用的存储),你可以改为返回一个 Slice。Slice 只知道是否有下一个 Slice,在遍历较大结果集时这可能就足够了。
排序选项也通过 Pageable 实例处理。如果你只需要排序,就在方法中添加一个 org.springframework.data.domain.Sort 参数。如你所见,返回 List 也是可以的。在这种情况下,不会创建构建实际 Page 实例所需的额外元数据(这反过来意味着不会发出本必需的额外 count 查询)。相反,它将查询限制为只查找给定范围内的实体。
要查明整个查询会得到多少页,你必须触发一个额外的 count 查询。默认情况下,该查询是从你实际触发的查询派生出来的。
特殊参数在一个查询方法内只能使用一次。
前面描述的某些特殊参数是互斥的。请考虑以下无效参数组合的列表。
| 参数 | 示例 | 原因 |
|---|---|---|
Pageable 和 Sort | findBy…(Pageable page, Sort sort) | Pageable 已定义了 Sort |
Pageable 和 Limit | findBy…(Pageable page, Limit limit) | Pageable 已定义了一个 limit。 |
Top 关键字可以与 Pageable 一起使用:Top 定义结果的总最大数量,而 Pageable 参数可能会进一步减少这个数量。
哪种方法合适?
Spring Data 抽象所提供的价值,或许最好通过下表所概述的可能查询方法返回类型来展示。该表显示了你可以从查询方法返回哪些类型。
表 1. 消费大型查询结果
| 方法 | 获取的数据量 | 查询结构 | 约束 |
|---|---|---|---|
| List<T> | 所有结果。 | 单条查询。 | 查询结果可能耗尽所有内存。获取所有数据可能很耗时。 |
| Streamable<T> | 所有结果。 | 单条查询。 | 查询结果可能耗尽所有内存。获取所有数据可能很耗时。 |
| Stream<T> | 分块(逐个或分批),取决于 Stream 的消费方式。 | 单条查询,通常使用游标。 | 流使用后必须关闭,以避免资源泄漏。 |
Flux<T> | 分块(逐个或分批),取决于 Flux 的消费方式。 | 单条查询,通常使用游标。 | 存储模块必须提供响应式基础设施。 |
Slice<T> | 在 Pageable.getOffset() 处取 Pageable.getPageSize() + 1 | 从 Pageable.getOffset() 开始获取数据、应用限制的一到多条查询。 | 一个 Slice 只能导航到下一个 Slice。- Slice 提供是否还有更多数据要获取的详细信息。- 当偏移量过大时,基于偏移量的查询会变得低效,因为数据库仍必须具体化完整结果。 |
Page<T> | 在 Pageable.getOffset() 处取 Pageable.getPageSize() | 从 Pageable.getOffset() 开始、应用限制的一到多条查询。此外,可能需要 COUNT(…) 查询来确定元素总数。 | 通常需要代价高昂的 COUNT(…) 查询。- 当偏移量过大时,基于偏移量的查询会变得低效,因为数据库仍必须具体化完整结果。 |
分页与排序
你可以使用属性名定义简单的排序表达式。你可以连接表达式,将多个条件收集到一个表达式中。
Sort sort = Sort.by("firstname").ascending()
.and(Sort.by("lastname").descending());
要以更类型安全的方式定义排序表达式,请从要为之定义排序表达式的类型开始,并使用方法引用来定义要排序的属性。
TypedSort<Person> person = Sort.sort(Person.class);
Sort sort = person.by(Person::getFirstname).ascending()
.and(person.by(Person::getLastname).descending());
TypedSort.by(…) 通过(通常)使用 CGlib 利用运行时代理,当使用 GraalVM Native Image 等工具时,这可能会干扰原生镜像编译。
如果你的存储实现支持 Querydsl,你也可以使用生成的元模型类型来定义排序表达式:
QSort sort = QSort.by(QPerson.firstname.asc())
.and(QSort.by(QPerson.lastname.desc()));
限制查询结果
除了分页之外,还可以使用专用的 Limit 参数来限制结果大小。你也可以使用 First 或 Top 关键字来限制查询方法的结果,这两个关键字可以互换使用,但不能与 Limit 参数混用。你可以在 Top 或 First 后附加一个可选的数值,以指定要返回的最大结果数。如果省略该数字,则假定结果大小为 1。以下示例展示了如何限制查询大小:
List<User> findByLastname(String lastname, Limit limit);
User findFirstByOrderByLastnameAsc();
User findTopByLastnameOrderByAgeDesc(String lastname);
Page<User> queryFirst10ByLastname(String lastname, Pageable pageable);
Slice<User> findTop3By(Pageable pageable);
List<User> findFirst10ByLastname(String lastname, Sort sort);
List<User> findTop10ByLastname(String lastname, Pageable pageable);
对于支持去重查询的数据存储,限制表达式还支持 Distinct 关键字。此外,对于将结果集限制为一个实例的查询,还支持用 Optional 关键字包装结果。
如果对一个限制查询应用了分页或切片(以及可用页数的计算),则它是在受限结果内应用的。
将结果限制与使用 Sort 参数的动态排序相结合,可以让你表达出针对最小的 'K' 个元素以及最大的 'K' 个元素的查询方法。