|
此版本仍在开发中，尚不被认为是稳定的。对于最新的稳定版本，请使用 Spring Data Commons 3.5.3！ |
定义查询方法
存储库代理有两种方法可以从方法名称派生特定于存储的查询：
-
通过直接从方法名称派生查询。
-
通过使用手动定义的查询。
可用选项取决于实际商店。 但是，必须有一个策略来决定创建什么实际查询。 下一节将介绍可用选项。
查询查找策略
存储库基础结构可以使用以下策略来解决查询。
使用 XML 配置，您可以通过query-lookup-strategy属性。
对于 Java 配置，您可以使用queryLookupStrategy属性的EnableJpaRepositories注解。
特定数据存储可能不支持某些策略。
-
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） 的属性都针对标识符属性，而不管声明的方法中使用的实际属性名称如何。
考虑以下包含属性的域类型pk通过@Id以及一个名为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)
}| 1 | 标识符属性（主键）。 |
| 2 | 名为id，但不是标识符。 |
| 3 | 将pk属性（标有@Id这被认为是标识符），因为它引用了CrudRepositorybase repository 方法。
因此，它不是使用id正如属性名称所暗示的那样，因为它是保留方法之一。 |
| 4 | 将pk属性，因为它是派生查询。 |
| 5 | 将id属性，使用find和by以避免与保留方法发生冲突。 |
这种特殊行为不仅针对查找方法，还适用于exits和delete的。
方法列表请参考“仓库查询关键词”。
属性表达式
属性表达式只能引用托管实体的直接属性，如前面的示例所示。 在查询创建时，已确保分析的属性是托管域类的属性。 但是，您也可以通过遍历嵌套属性来定义约束。 考虑以下方法签名：
List<Person> findByAddressZipCode(ZipCode zipCode);假设一个Person有一个Address使用ZipCode.
在这种情况下，该方法会创建x.address.zipCode属性遍历。
分辨率算法首先解释整个零件 （AddressZipCode） 作为属性，并检查域类中是否存在具有该名称（未大写）的属性。
如果算法成功，它将使用该属性。
如果没有，算法会将右侧驼峰式部分的源拆分为正面和尾部，并尝试找到相应的属性——在我们的示例中，AddressZip和Code.
如果算法找到具有该头部的属性，它就会采用尾部并从那里继续构建树，以刚才描述的方式将尾部拆分。
如果第一个拆分不匹配，则算法将拆分点向左移动（Address,ZipCode）并继续。
尽管这应该适用于大多数情况，但算法可能会选择错误的属性。
假设Person类有一个addressZip属性也是如此。
该算法将在第一轮拆分中匹配，选择错误的属性，然后失败（作为addressZip可能没有code属性）。
要解决此歧义，您可以在方法名称中使用手动定义遍历点。
因此，我们的方法名称如下：_
List<Person> findByAddress_ZipCode(ZipCode zipCode);|
因为我们将下划线 （） 视为保留字符，所以我们强烈建议遵循标准的 Java 命名约定（即，不要在属性名称中使用下划线，而是应用驼峰式命名法）。 |
|
以下划线开头的字段名称：
字段名称可以以下划线开头，例如 大写字段名称：
全大写的字段名称可以这样使用。
嵌套路径（如果适用）需要拆分过孔，如 第二个大写字母的字段名称：
由起始小写字母后跟大写字母组成的字段名称，例如 路径歧义：
在以下示例中，属性的排列 由于首先考虑属性上的直接匹配，因此不会考虑任何潜在的嵌套路径，并且算法会选择 |
返回集合或可迭代对象的存储库方法
返回多个结果的查询方法可以使用标准 JavaIterable,List和Set.
除此之外，我们支持返回 Spring Data 的Streamable，的自定义扩展Iterable，以及 Vavr 提供的集合类型。
请参阅说明所有可能的查询方法返回类型的附录。
使用 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"));返回自定义可流式传输包装器类型
为集合提供专用包装器类型是一种常用的模式，用于为返回多个元素的查询结果提供 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 implements Repository<Product, Long> {
Products findAllByDescriptionContaining(String text); (5)
}| 1 | 一个Product实体，该实体公开 API 以访问产品的价格。 |
| 2 | 的包装器类型Streamable<Product>可以通过使用Products.of(…)（使用 Lombok 注释创建的工厂方法）。
一个标准构造函数将Streamable<Product>也会这样做。 |
| 3 | 包装器类型公开了一个额外的 API，计算Streamable<Product>. |
| 4 | 实现Streamable接口并委托给实际结果。 |
| 5 | 该包装器类型Products可以直接用作查询方法返回类型。
您无需退货Streamable<Product>并在存储库客户端中的查询后手动包装它。 |
支持 Vavr 集合
Vavr 是一个包含 Java 函数式编程概念的库。 它附带了一组自定义集合类型，可将其用作查询方法返回类型，如下表所示：
| Vavr 收集类型 | 使用Vavr实现类型 | 有效的 Java 源代码类型 |
|---|---|---|
|
|
|
|
|
|
|
|
|
您可以使用第一列中的类型（或其子类型）作为查询方法返回类型，并获取第二列中的类型作为实现类型，具体取决于实际查询结果（第三列）的 Java 类型。
或者，您可以声明Traversable（瓦夫尔Iterable等效），然后我们从实际返回值派生实现类。
也就是说，一个java.util.List变成了 VavrList或Seq一个java.util.Set成为 VavrLinkedHashSet Set，依此类推。
流式查询结果
您可以使用 Java 8 以增量方式处理查询方法的结果Stream<T>作为返回类型。
而不是将查询结果包装在Stream，则特定于数据存储的方法用于执行流式处理，如以下示例所示：
Stream<T>@Query("select u from User u")
Stream<User> findAllByCustomQueryAndStream();
Stream<User> readAllByFirstnameNotNull();
@Query("select u from User u")
Stream<User> streamAllPaged(Pageable pageable);一个Stream可能会包装特定于基础数据存储的资源，因此必须在使用后关闭。
您可以手动关闭Stream通过使用close()方法或使用 Java 7try-with-resources块，如以下示例所示： |
Stream<T>导致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)| 1 | 用java.util.concurrent.Future作为返回类型。 |
| 2 | 使用 Java 8java.util.concurrent.CompletableFuture作为返回类型。 |
分页、迭代大型结果、排序和限制
若要处理查询中的参数，请定义方法参数，如前面的示例中已看到。
除此之外，基础设施还可以识别某些特定类型，例如Pageable,Sort和Limit，以动态地将分页、排序和限制应用于查询。
以下示例演示了这些功能：
Pageable,Slice,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);获取 APISort,Pageable和Limit预计不会null值。
如果您不想应用任何排序或分页，请使用Sort.unsorted(),Pageable.unpaged()和Limit.unlimited(). |
第一种方法允许您将org.springframework.data.domain.Pageableinstance 添加到查询方法，以动态地将分页添加到静态定义的查询中。
一个Page了解可用元素和页面的总数。
它通过基础设施触发计数查询来计算总数来实现这一点。
由于这可能会很昂贵（取决于所使用的商店），您可以返回Slice.
一个Slice只知道下一个Slice可用，这在遍历更大的结果集时可能就足够了。
排序选项通过Pageable实例也是如此。
如果只需要排序，请添加org.springframework.data.domain.Sort参数添加到您的方法。
如您所见，返回一个List也是可能的。
在这种情况下，构建实际Page实例不会创建（这反过来意味着不会发出必要的附加计数查询）。
相反，它限制查询仅查找给定的实体范围。
| 要了解整个查询获得的页面数，您必须触发额外的计数查询。 默认情况下，此查询派生自实际触发的查询。 |
|
特殊参数在查询方法中只能使用一次。上述
这 |
哪种方法合适？
Spring Data 抽象提供的值可能最好通过下表中概述的可能查询方法返回类型来显示。 该表显示了可以从查询方法返回哪些类型
| 方法 | 获取的数据量 | 查询结构 | 约束 |
|---|---|---|---|
所有结果。 |
单个查询。 |
查询结果可能会耗尽所有内存。获取所有数据可能非常耗时。 |
|
所有结果。 |
单个查询。 |
查询结果可能会耗尽所有内存。获取所有数据可能非常耗时。 |
|
分块（逐个或批量）取决于 |
使用典型游标的单个查询。 |
使用后必须关闭流，以免资源泄漏。 |
|
|
分块（逐个或批量）取决于 |
使用典型游标的单个查询。 |
Store 模块必须提供响应式基础设施。 |
|
|
一对多查询，提取数据开头为 |
一个
|
|
|
一对多查询，开头为 |
很多时候，
|
分页和排序
可以使用属性名称定义简单的排序表达式。 您可以连接表达式以将多个条件收集到一个表达式中。
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 来使用运行时代理，这在使用 Graal VM Native 等工具时可能会干扰本机映像编译。 |
如果您的商店实现支持 Querydsl，您还可以使用生成的元模型类型来定义排序表达式：
QSort sort = QSort.by(QPerson.firstname.asc())
.and(QSort.by(QPerson.lastname.desc()));限制查询结果
除了分页之外，还可以使用专用的Limit参数。
您还可以使用First或Top关键字，您可以互换使用，但不能与Limit参数。
您可以将可选的数值附加到Top或First以指定要返回的最大结果大小。
如果省略该数字，则假定结果大小为 1。
以下示例演示如何限制查询大小：
Top和FirstList<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”的查询方法。 |