|
此版本仍在开发中，尚未被视为稳定版本。如需最新稳定版本，请使用 Spring Data Cassandra 5.0.4！ |
定义查询方法
仓库代理有两种方式根据方法名派生出特定于存储的查询：
-
通过直接从方法名派生查询。
-
通过使用手动定义的查询。
可用的选项取决于实际使用的存储。 然而，必须有一种策略来决定实际生成的查询是什么。 下一节将介绍可用的选项。
查询查找策略
以下策略可供仓库基础设施用于解析查询。
使用 XML 配置时，可以通过命名空间的 query-lookup-strategy 属性来配置该策略。
对于 Java 配置，可以使用 queryLookupStrategy 注解的 EnableCassandraRepositories 属性。
某些策略可能不被特定的数据存储所支持。
-
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 用于在要创建的查询上设置 distinct 标志，或 Top/First 用于限制查询结果。
附录包含了查询方法主题关键字的完整列表以及包含排序和大小写修饰符的查询方法谓词关键字。
然而，第一个By充当分隔符，用于指示实际条件谓词的开始。
在最基本层面上，你可以定义实体属性上的条件，并使用And和Or将它们连接起来。
解析该方法的实际结果取决于您为其创建查询的持久化存储。 然而，有一些通用事项需要注意：
-
表达式通常是属性遍历与可串联的操作符组合而成。 你可以使用
AND和OR将属性表达式组合起来。 你还可以在属性表达式中使用诸如Between、LessThan、GreaterThan和Like等操作符。 所支持的操作符可能因数据存储而异，因此请查阅参考文档中的相应部分。 -
方法解析器支持为单个属性设置
IgnoreCase标志（例如，findByLastnameIgnoreCase(…)），或者为所有支持忽略大小写的属性类型（通常是String类型的实例）设置该标志（例如，findByLastnameAndFirstnameAllIgnoreCase(…)）。 是否支持忽略大小写可能因数据存储而异，因此请查阅参考文档中与特定存储相关的查询方法部分。 -
你可以通过在查询方法后附加一个
OrderBy子句（引用某个属性）并指定排序方向（Asc或Desc）来应用静态排序。 若要创建支持动态排序的查询方法，请参阅“分页、迭代大型结果集、排序与限制”。
保留方法名
虽然派生的仓库方法通常通过名称绑定到属性，但在某些情况下，从基础仓库继承的、针对标识符（identifier）属性的特定方法名会例外。
这些保留方法（reserved methods），例如 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 注解标记、被视为标识符的属性），因为这引用了 CrudRepository 基础仓库的一个方法。
因此，它并不是一个派生查询，尽管从属性名 id 看似如此，因为该方法属于保留方法之一。 |
| 4 | 通过名称 targeting pk 属性，因为这是一个派生查询。 |
| 5 | 通过在 id 和 find 之间使用描述性标记来定位 by 属性，以避免与保留方法发生冲突。 |
这种特殊行为不仅适用于查找方法，也适用于 exits 和 delete 方法。
有关方法列表，请参阅“Repository 查询关键字”。
属性表达式
属性表达式只能引用被管理实体的直接属性，如前面示例所示。 在查询创建时，您已经确保所解析的属性是被管理领域类的一个属性。 然而，您也可以通过遍历嵌套属性来定义约束条件。 请考虑以下方法签名：
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 Iterable、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（即 Vavr 中与 Iterable 等价的类型），此时我们会根据实际返回值推导出具体的实现类。
例如，java.util.List 会被转换为 Vavr 的 List 或 Seq，java.util.Set 则会变成 Vavr 的 LinkedHashSet 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 7 的 try-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 8 的 java.util.concurrent.CompletableFuture 作为返回类型。 |
分页、迭代大量结果、排序与限制
要在查询中处理参数，请像前面示例中那样定义方法参数。
除此之外，基础设施还能识别某些特定类型，例如 Pageable、Sort 和 Limit，以便动态地为您的查询应用分页、排序和限制功能。
以下示例演示了这些特性：
Pageable、Slice、ScrollPosition、Sort 和 LimitPage<User> findByLastname(String lastname, Pageable pageable);
Slice<User> findByLastname(String lastname, Pageable pageable);
Window<User> findTop10ByLastname(String lastname, ScrollPosition position, Sort sort);
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 实例所需的额外元数据（这意味着原本必需的额外计数查询也不会被执行）。
而是仅限制查询以检索指定范围内的实体。
| 要了解整个查询会返回多少页，您需要触发一个额外的计数查询。 默认情况下，该查询是从您实际触发的查询中派生而来的。 |
|
特殊参数在查询方法中只能使用一次。
|
哪种方法合适？
Spring Data 抽象所提供的价值，或许最好通过下表中列出的可能的查询方法返回类型来体现。 该表展示了你可以从查询方法中返回哪些类型。
| 方法 | 获取的数据量 | 查询结构 | 约束条件 |
|---|---|---|---|
所有结果。 |
单个查询。 |
查询结果可能会耗尽所有内存。获取全部数据可能非常耗时。 |
|
所有结果。 |
单个查询。 |
查询结果可能会耗尽所有内存。获取全部数据可能非常耗时。 |
|
根据 |
通常使用游标的单个查询。 |
使用完流后必须关闭，以避免资源泄漏。 |
|
|
根据 |
通常使用游标的单个查询。 |
存储模块必须提供响应式基础设施。 |
|
|
从 |
|
基于偏移量的 |
|
从 |
|
|
|
从 |
通常情况下，需要执行开销较大的
|
基于键集的 |
使用重写的 |
从 |
|
分页与排序
你可以通过使用属性名称来定义简单的排序表达式。 你可以将多个表达式连接起来，将多个排序条件合并为一个表达式。
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 和 First 限制查询结果的数量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”个最大元素的查询方法。 |