定义查询方法

Repository 代理有两种方式从方法名推导存储特定的查询

  • 通过直接从方法名推导查询。

  • 通过使用手动定义的查询。

可用的选项取决于实际的存储。但是，必须有一种策略来决定创建什么样的实际查询。下一节描述了可用的选项。

查询查找策略

Repository 基础设施可以通过以下策略来解析查询。使用 XML 配置时，可以通过命名空间的 query-lookup-strategy 属性配置策略。对于 Java 配置，可以使用 EnableJpaRepositories 注解的 queryLookupStrategy 属性。某些策略可能不适用于特定的数据存储。

  • CREATE 尝试从查询方法名构造存储特定的查询。通常的方法是移除方法名中已知的前缀集，然后解析方法的其余部分。你可以在“查询创建”中阅读更多关于查询构造的信息。

  • USE_DECLARED_QUERY 尝试查找已声明的查询，如果找不到则抛出异常。查询可以通过注解或其他方式定义。请参阅特定存储的文档以查找该存储可用的选项。如果在启动时 Repository 基础设施找不到方法的已声明查询，则会失败。

  • CREATE_IF_NOT_FOUND（默认）结合了 CREATE 和 USE_DECLARED_QUERY。它首先查找已声明的查询，如果找不到已声明的查询，则创建一个基于方法名的自定义查询。这是默认的查找策略，因此，如果你没有明确配置任何内容，则会使用此策略。它允许通过方法名快速定义查询，也可以通过引入已声明的查询按需自定义调整这些查询。

查询创建

Spring Data Repository 基础设施中内置的查询构建器机制对于构建针对 Repository 实体进行约束的查询非常有用。

以下示例展示了如何创建多个查询

从方法名创建查询
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 等运算符。支持的运算符可能因数据存储而异，因此请查阅参考文档的相应部分。

  • 方法解析器支持为单个属性（例如，findByLastnameIgnoreCase(…)）或支持忽略大小写的类型的所有属性（通常是 String 实例——例如，findByLastnameAndFirstnameAllIgnoreCase(…)）设置 IgnoreCase 标志。是否支持忽略大小写可能因存储而异，因此请查阅参考文档中特定存储的查询方法相关部分。

  • 你可以通过向查询方法追加引用属性的 OrderBy 子句并提供排序方向（Asc 或 Desc）来应用静态排序。要创建支持动态排序的查询方法，请参阅“分页、迭代大结果集、排序和限制”。

保留方法名

虽然派生的 Repository 方法按名称绑定到属性，但在涉及从目标是 *identifier* 属性的基础 Repository 继承的某些方法名时，此规则有一些例外。那些 *保留方法*，如 CrudRepository#findById（或仅 findById），无论声明的方法中使用的实际属性名是什么，都以 *identifier* 属性为目标。

考虑以下域类型，它持有一个通过 @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)
}
1 标识符属性（主键）。
2 一个名为 id 的属性，但不是标识符。
3 它以 pk 属性（标记有 @Id 并被认为是标识符的那个）为目标，因为它引用了 CrudRepository 的基础 Repository 方法。因此，它不是一个使用 id 的派生查询，尽管属性名可能暗示如此，因为它是一个 *保留方法*。
4 它按名称以 pk 属性为目标，因为它是一个派生查询。
5 它通过使用 find 和 by 之间的描述性标记来避免与 *保留方法* 冲突，从而以 id 属性为目标。

这种特殊行为不仅适用于查找方法，也适用于 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 命名规范（即，在属性名中不使用下划线，而是使用驼峰命名法）。
以下划线开头的字段名

字段名可能以下划线开头，例如 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。

返回集合或 Iterables 的 Repository 方法

返回多个结果的查询方法可以使用标准的 Java Iterable, List 和 Set。此外，我们支持返回 Spring Data 的 Streamable（它是 Iterable 的自定义扩展），以及 Vavr 提供的集合类型。请参阅附录，了解所有可能的查询方法返回类型。

将 Streamable 用作查询方法返回类型

你可以使用 Streamable 作为 Iterable 或任何集合类型的替代。它提供了方便的方法来访问非并行 Stream (Iterable 所没有的)，以及直接对元素进行 ….filter(…) 和 ….map(…) 操作，并将 Streamable 与其他 Streamable 连接起来。

使用 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。通常，这些类型是通过调用返回集合类型数据的 Repository 方法并手动创建包装器类型实例来使用的。你可以避免这个额外的步骤，因为 Spring Data 允许你将这些包装器类型用作查询方法的返回类型，如果它们满足以下条件

  1. 该类型实现了 Streamable。

  2. 该类型公开了接受 Streamable 作为参数的构造函数或名为 of(…) 或 valueOf(…) 的静态工厂方法。

以下列表展示了一个示例

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> 并在 Repository 客户端查询后手动包装它。

支持 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，等等。

流式查询结果

你可以通过使用 Java 8 Stream<T> 作为返回类型来增量处理查询方法的结果。与将查询结果包装在 Stream 中不同，这里使用数据存储特定的方法来执行流式处理，如下例所示

使用 Java 8 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 可能包装了底层数据存储特定的资源，因此使用后必须关闭。你可以通过使用 close() 方法手动关闭 Stream，或者使用 Java 7 的 try-with-resources 块，如下例所示
在 try-with-resources 块中使用 Stream<T> 结果
try (Stream<User> stream = repository.findAllByCustomQueryAndStream()) {
  stream.forEach(…);
}
并非所有 Spring Data 模块目前都支持 Stream<T> 作为返回类型。

异步查询结果

你可以使用Spring 的异步方法运行能力异步运行 Repository 查询。这意味着方法在调用后立即返回，而实际查询发生在提交给 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、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 知道总元素数和可用页数。它是通过基础设施触发计数查询来计算总数的。由于这可能很昂贵（取决于使用的存储），你可以改为返回一个 Slice。Slice 只知道是否还有下一个 Slice 可用，这在遍历大型结果集时可能足够了。

排序选项也通过 Pageable 实例处理。如果只需要排序，请在方法中添加 org.springframework.data.domain.Sort 参数。如你所见，返回 List 也是可能的。在这种情况下，构建实际 Page 实例所需的额外元数据不会被创建（这反过来意味着原本必需的额外计数查询不会被发出）。相反，它将查询限制为仅查找给定范围的实体。

要了解整个查询有多少页，你必须触发额外的计数查询。默认情况下，此查询是根据你实际触发的查询派生的。

特殊参数在查询方法中只能使用一次。
上面描述的一些特殊参数是互斥的。请考虑以下无效参数组合列表。

参数 示例 原因

Pageable 和 Sort

findBy…​(Pageable page, Sort sort)

Pageable 已定义 Sort

Pageable 和 Limit

findBy…​(Pageable page, Limit limit)

Pageable 已定义限制。

用于限制结果的 Top 关键字可以与 Pageable 一起使用，其中 Top 定义了结果的总最大值，而 Pageable 参数可能会减少此数值。

哪种方法合适？

Spring Data 抽象提供的价值或许最能通过下表列出的可能的查询方法返回类型来展示。下表显示了你可以从查询方法返回哪些类型

表 1. 处理大型查询结果
方法 获取的数据量 查询结构 限制

List<T>

所有结果。

单个查询。

查询结果可能耗尽所有内存。获取所有数据可能耗时。

Streamable<T>

所有结果。

单个查询。

查询结果可能耗尽所有内存。获取所有数据可能耗时。

Stream<T>

分块（逐个或批量），取决于 Stream 的消费方式。

通常使用游标的单个查询。

使用后必须关闭 Stream 以避免资源泄露。

Flux<T>

分块（逐个或批量），取决于 Flux 的消费方式。

通常使用游标的单个查询。

存储模块必须提供响应式基础设施。

Slice<T>

在 Pageable.getOffset() 处获取 Pageable.getPageSize() + 1

从 Pageable.getOffset() 开始获取数据的查询（一个或多个），并应用限制。

Slice 只能导航到下一个 Slice。

  • Slice 提供了是否有更多数据可获取的详细信息。

  • 当 offset 过大时，基于 offset 的查询会变得低效，因为数据库仍然需要实现完整的结果集。

  • Window 提供了是否有更多数据可获取的详细信息。

  • 当 offset 过大时，基于 offset 的查询会变得低效，因为数据库仍然需要实现完整的结果集。

Page<T>

在 Pageable.getOffset() 处获取 Pageable.getPageSize()

从 Pageable.getOffset() 开始获取数据的查询（一个或多个），并应用限制。此外，可能需要 COUNT(…) 查询来确定元素的总数。

COUNT(…) 查询通常是必需的，但成本较高。

  • 当 offset 过大时，基于 offset 的查询会变得低效，因为数据库仍然需要实现完整的结果集。

分页和排序

你可以使用属性名定义简单的排序表达式。你可以连接表达式将多个条件组合成一个表达式。

定义排序表达式
Sort sort = Sort.by("firstname").ascending()
  .and(Sort.by("lastname").descending());

为了以更类型安全的方式定义排序表达式，请从要定义排序表达式的类型开始，并使用方法引用定义要排序的属性。

使用类型安全 API 定义排序表达式
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，你还可以使用生成的元模型类型定义排序表达式

使用 Querydsl API 定义排序表达式
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 关键字，适用于支持 distinct 查询的数据存储。此外，对于将结果集限制为一个实例的查询，支持使用 Optional 关键字包装结果。

如果将分页或切片应用于限制性查询的分页（以及可用页数的计算），则它会应用于受限结果集内部。

将限制结果集与使用 Sort 参数进行的动态排序结合，可以让你表达获取“K”个最小或“K”个最大元素的查询方法。