Spring Data Repository 使用详解

8.1. 核心概念

Spring Data repository 抽象的中心接口是 Repository。它把要管理的 domain 类以及 domain 类的ID类型作为泛型参数。这个接口主要是作为一个标记接口，用来捕捉工作中的类型，并帮助你发现扩展这个接口的接口。 CrudRepository 和 ListCrudRepository 接口为被管理的实体类提供复杂的CRUD功能。

Example 3. CrudRepository 接口

public interface CrudRepository extends Repository {

   S save(S entity);      

  Optional findById(ID primaryKey); 

  Iterable findAll();               

  long count();                        

  void delete(T entity);               

  boolean existsById(ID primaryKey);   

  // … more functionality omitted.
}

	保存给定的实体。
	根据ID返回实体。
	返回所有实体。
	返回实体数量。
	删除给定的实体。
	根据ID判断实体是否存在。

ListCrudRepository 提供了同等的方法，但它们返回 List，而 CrudRepository 的方法返回 Iterable。

我们还提供了持久化技术的特定抽象，如 JpaRepository 或 MongoRepository。这些接口扩展了 CrudRepository，除了像 CrudRepository 这样相当通用的持久化技术的接口之外，还暴露了底层持久化技术的能力。

除了 CrudRepository 之外，还有一个 PagingAndSortingRepository 的抽象，它增加了额外的分页，排序方法。

Example 4. PagingAndSortingRepository 接口

public interface PagingAndSortingRepository  {

  Iterable findAll(Sort sort);

  Page findAll(Pageable pageable);
}

例如，访问第2页的 User ，每页20条数据，你可以这样：

PagingAndSortingRepository repository = // … get access to a bean
Page users = repository.findAll(PageRequest.of(1, 20));

除了 query 方法外，count 和 delete 查询的查询派生也是可用的。下面的列表显示了派生的 count 查询的接口定义。

Example 5. Derived Count Query

interface UserRepository extends CrudRepository {

  long countByLastname(String lastname);
}

下面的列表显示了一个派生的 delete 查询的接口定义。

Example 6. Derived Delete Query

interface UserRepository extends CrudRepository {

  long deleteByLastname(String lastname);

  List removeByLastname(String lastname);
}

8.2. Query 方法

标准的CRUD Repository 通常有对底层数据store的查询。使用Spring Data，声明这些查询成为一个四步过程。

1. 声明一个扩展 Repository 或其子接口之一的接口，并将其泛型指定为它应该处理的domain类和ID类型，如以下例子所示。
2. interface PersonRepository extends Repository { … }
3. 在接口中声明query方法。
4. interface PersonRepository extends Repository { List findByLastname(String lastname); }
5. 设置Spring为这些接口创建代理实例，可以用JavaConfig或XML 配置。
6. Java
7. XML
8. @EnableMongoRepositories class Config { … }
9. 本例中使用的是JPA namespace。如果你对任何其他store使用 Repository 抽象，你需要把它改为你的store模块的适当 namespace 声明。换句话说，你应该把 jpa 换成，例如 mongodb。
10. 请注意，JavaConfig 并没有明确地配置 package，因为被注解的类的 package 是默认使用的。要自定义要扫描的包，请使用数据store特定库的 @EnableMongoRepositories 注解的 basePackage…​ 属性之一。
11. class SomeClient { private final PersonRepository repository; SomeClient(PersonRepository repository) { this.repository = repository; } void doSomething() { List persons = repository.findByLastname("Matthews"); } }

下面的章节将详细解释每一个步骤。

• 定义 Repository 接口
• 定义 Query 方法
• 创建 Repository 实例
• 自定义 Spring Data Repository 的实现

8.3. 定义 Repository 接口

要定义一个 repository 接口，你首先需要定义一个domain类专用的 repository 接口。该接口必须继承 Repository，并将其泛型设置为domain类和ID类。如果你想为该domain类公开CRUD方法，你可以继承 CrudRepository，或其变体，而不是 Repository。

8.3.1. 稍微修改 Repository 的定义

有几种变体可以让你开始使用你的 repository 接口。

典型的方法是继承 CrudRepository，它为你提供了 CRUD 功能的方法。CRUD是指创建、读取、更新、删除。在3.0版本中，我们还引入了 ListCrudRepository，它与 CrudRepository 非常相似，但对于那些返回多个实体的方法，它返回一个 List 而不是一个 Iterable，你可能会发现它更容易使用。

如果你使用的是响应式store，你可以选择 ReactiveCrudRepository，或者 RxJava3CrudRepository，这取决于你使用的是哪种响应式框架。

如果你使用的是Kotlin，你可以选择 CoroutineCrudRepository，它利用了Kotlin的 coroutine（协程）。

额外的你可以扩展 PagingAndSortingRepository、ReactiveSortingRepository、RxJava3SortingRepository 或 CoroutineSortingRepository，如果你需要允许指定一个 Sort 抽象的方法，或者在第一种情况下是 Pageable 抽象。请注意，各种排序 repository 不再像Spring Data 3.0之前的版本那样扩展各自的CRUD库。因此，如果你想获得这两个接口的功能，你需要扩展这两个接口。

如果你不想扩展Spring Data接口，你也可以用 @RepositoryDefinition 来注解你的 repository 接口。扩展CRUD repository 接口之一会暴露出一套完整的方法来操作你的实体。如果你想对暴露的方法有所选择，可以从CRUD repository 复制你想暴露的方法到你的 domain repository。这样做时，你可以改变方法的返回类型。如果可能的话，Spring Data会尊重返回类型。例如，对于返回多个实体的方法，你可以选择 Iterable、List、Collection 或 VAVR list

如果你的应用程序中的许多 repository 应该有相同的方法集，你可以定义你自己的基础接口来继承。这样的接口必须用 @NoRepositoryBean 来注释。这可以防止Spring Data试图直接创建它的实例而导致异常，因为它仍然包含一个泛型变量，Spring data 无法确定该 repository 的实体。

下面的例子展示了如何有选择地公开CRUD方法（本例中为 findById 和 save）。

Example 7. Selectively exposing CRUD methods

@NoRepositoryBean
interface MyBaseRepository extends Repository {

  Optional findById(ID id);

   S save(S entity);
}

interface UserRepository extends MyBaseRepository {
  User findByEmailAddress(EmailAddress emailAddress);
}

在前面的例子中，你为所有的 domain repository 定义了一个通用的基础接口，并暴露了 findById(…​) 以及 save(…​)。这些方法被路由到Spring Data提供的你所选择的store的基础 repository 实现（例如，如果你使用JPA，实现是 SimpleJpaRepository），因为它们与 CrudRepository 中的方法签名一致。 所以 UserRepository 现在可以保存用户，通过ID查找单个用户，通过电子邮件地址查找 User。

中间的 repository 接口被注解为 @NoRepositoryBean。确保你在所有Spring Data不应该在运行时创建实例的 repository 接口上添加该注解。

8.3.2. 在多个Spring数据模块中使用 Repository

在你的应用程序中使用一个独特的Spring Data模块使事情变得简单，因为定义范围内的所有 repository 接口都绑定到Spring Data模块。有时，应用程序需要使用一个以上的Spring Data模块。在这种情况下，repository 定义必须区分持久化技术。当它检测到类路径上有多个 repository 工厂时，Spring Data会进入严格的 repository 配置模式。严格的配置使用 repository 或domain类的细节来决定 repository 定义的Spring Data模块绑定。

1. 如果 repository 定义 继承了特定模块的 repository，那么它就是特定Spring Data模块的有效候选 repository。
2. 如果 domain 类被注解了 模块特定的类型注解，它就是特定Spring Data模块的有效候选者。Spring Data模块接受第三方注解（如JPA的 @Entity）或提供自己的注解（如Spring Data MongoDB和Spring Data Elasticsearch的 @Document）。

下面的例子显示了一个使用特定模块接口的 repository（本例中为JPA）。

Example 8. 使用模块特定接口的 Repository 定义

interface MyRepository extends JpaRepository { }

@NoRepositoryBean
interface MyBaseRepository extends JpaRepository { … }

interface UserRepository extends MyBaseRepository { … }

MyRepository 和 UserRepository 在其类型层次上扩展了 JpaRepository。它们是Spring Data JPA 模块的有效候选者。

下面的例子显示了一个使用通用（泛型）接口的 repository。

Example 9. 使用泛型接口的 repository 定义

interface AmbiguousRepository extends Repository { … }

@NoRepositoryBean
interface MyBaseRepository extends CrudRepository { … }

interface AmbiguousUserRepository extends MyBaseRepository { … }

AmbiguousRepository 和 AmbiguousUserRepository 在其类型层次结构中只继承了 Repository 和 CrudRepository 。虽然在使用唯一的Spring Data模块时这很好，但多个模块无法区分这些 repository 应该被绑定到哪个特定的Spring Data。

下面的例子显示了一个使用带注解的domain类的repository。

Example 10. 使用带注解的 domain 类的Repository 定义

interface PersonRepository extends Repository { … }

@Entity
class Person { … }

interface UserRepository extends Repository { … }

@Document
class User { … }

PersonRepository 引用了 Person，它被 JPA 的 @Entity 注解所注解，所以这个 repository 显然属于Spring Data JPA。UserRepository 引用了 User，它被Spring Data MongoDB 的 @Document 注解所注解。

下面的坏例子显示了一个使用混合注解的 domain 类的 Repository。

Example 11. 使用具有混合注解的 domain 类的 repository 定义

interface JpaPersonRepository extends Repository { … }

interface MongoDBPersonRepository extends Repository { … }

@Entity
@Document
class Person { … }

这个例子展示了一个同时使用JPA和Spring Data MongoDB注解的 domain 类。它定义了两个repository：JpaPersonRepository 和 MongoDBPersonRepository。一个用于JPA，另一个用于MongoDB的使用。Spring Data不再能够区分这些repository，这导致了未定义的行为。

Repository 类型细节和区分domain类注解用于严格的repository库配置，以确定特定Spring Data模块的repository候选者。在同一domain类型上使用多个持久化技术的特定注解是可能的，并且能够在多个持久化技术中重复使用domain类型。然而，Spring Data就不能再确定一个唯一的模块来绑定repository了。

区分 repository 的最后一个方法是通过对 repository base package的扫描。base package 定义了扫描 repository 接口定义的起点，这意味着将 repository 的定义放在适当的包中。默认情况下，注解驱动的配置使用配置类所在的base package。基于XML的配置中的base package，需要手动强制配置。

下面的例子显示了注解驱动的 base package 的配置。

Example 12. 注解驱动的 base package 的配置

@EnableJpaRepositories(basePackages = "com.acme.repositories.jpa")
@EnableMongoRepositories(basePackages = "com.acme.repositories.mongo")
class Configuration { … }

8.4. 定义 Query 方法

repository 代理有两种方法可以从方法名中推导出 repository 特定的查询。

• 通过直接从方法名派生出查询。
• 通过使用手动定义的查询。

可用的选项取决于实际的store。然而，必须有一个策略来决定创建什么样的实际查询。下一节将介绍可用的选项。

8.4.1. Query 的查询策略

下列策略可用于 repository 基础设施解析查询。 对于 XML 配置，你可以通过 query-lookup-strategy 属性在命名空间配置策略。 对于 Java 配置，你可以使用 EnableMongoRepositories 注解的 queryLookupStrategy 属性。有些策略可能不支持特定的datastore。

• CREATE 试图从查询方法名称中构建一个特定的存储查询。一般的做法是从方法名中删除一组已知的前缀，然后解析方法的其余部分。你可以在 “Query 创建” 中阅读更多关于查询构建的信息。 USE_DECLARED_QUERY 试图找到一个已声明的查询，如果找不到就会抛出一个异常。查询可以由某处的注解来定义，也可以通过其他方式来声明。请参阅特定store的文档以找到该store的可用选项。如果 repository 基础设施在启动时没有为该方法找到一个已声明的查询，则会失败。
• CREATE_IF_NOT_FOUND (默认) 结合了 CREATE 和 USE_DECLARED_QUERY。它首先查找一个已声明的查询， 如果没有找到已声明的查询， 它将创建一个基于方法名的自定义查询。这是默认的查询策略，因此，如果你没有明确地配置任何东西，就会使用这种策略。它允许通过方法名快速定义查询，但也可以根据需要通过引入已声明的查询对这些查询进行自定义调整。

8.4.2. Query 创建

内置在Spring Data repository 基础架构中的查询 builder 机制对于在资源库的实体上建立约束性查询非常有用。

下面的例子展示了如何创建一些查询。

Example 13. Query creation from method names

interface PersonRepository extends Repository {

  List findByEmailAddressAndLastname(EmailAddress emailAddress, String lastname);

  // Enables the distinct flag for the query
  List findDistinctPeopleByLastnameOrFirstname(String lastname, String firstname);
  List findPeopleDistinctByLastnameOrFirstname(String lastname, String firstname);

  // Enabling ignoring case for an individual property
  List findByLastnameIgnoreCase(String lastname);
  // Enabling ignoring case for all suitable properties
  List findByLastnameAndFirstnameAllIgnoreCase(String lastname, String firstname);

  // Enabling static ORDER BY for a query
  List findByLastnameOrderByFirstnameAsc(String lastname);
  List findByLastnameOrderByFirstnameDesc(String lastname);
}

解析查询方法名称分为主语和谓语。第一部分（find…​By, exists…​By）定义了查询的主语，第二部分形成谓语。引入句（主语）可以包含进一步的表达。在 find（或其他引入关键词）和 By 之间的任何文本都被认为是描述性的，除非使用一个限制结果的关键词，如 Distinct 在要创建的查询上设置一个不同的标志，或 Top / First 来限制查询结果。

附录中包含了 查询方法主语关键词 和 查询方法谓语关键词的完整列表，包括排序和字母修饰语。然而，第一个 By 作为分界符，表示实际条件谓词的开始。在一个非常基本的层面上，你可以在实体属性上定义条件，并用 And 和 Or 来连接它们。

解析方法的实际结果取决于你为之创建查询的持久性store。然而，有一些东西需要注意。

• 表达式通常是属性遍历与可以串联的运算符的组合。你可以用 AND 和 OR 来组合属性表达式。你还可以得到对属性表达式的运算符的支持，如 Between, LessThan, GreaterThan, 和 Like。支持的运算符可能因 datastore 的不同而不同，所以请查阅参考文档的适当部分。
• 方法解析器支持为单个属性（例如，findByLastnameIgnoreCase(…​)）或支持忽略大小写的类型的所有属性（通常是字符串实例—​例如，findByLastnameAndFirstnameAllIgnoreCase(…​)）设置忽略大小写标志。是否支持忽略大小写可能因store而异，所以请查阅参考文档中的相关章节，了解特定store的查询方法。
• 你可以通过在引用属性的查询方法中附加一个 OrderBy 子句，并提供一个排序方向（Asc 或 Desc）来应用静态排序。要创建一个支持动态排序的查询方法，请参阅 “特殊参数处理”。

8.4.3. 属性表达式

属性表达式只能引用被管理实体的一个直接属性，如前面的例子所示。在查询创建时，你已经确保解析的属性是被管理的domian类的一个属性。然而，你也可以通过遍历嵌套属性来定义约束。考虑一下下面的方法签名。

List findByAddressZipCode(ZipCode zipCode);

假设 Person 有一个带有 ZipCode 的 Address。在这种情况下，该方法创建 x.address.zipCode 属性遍历。解析算法首先将整个部分（AddressZipCode）解释为属性，并检查domain类中是否有该名称的属性（未加首字母）。如果算法成功，它就使用该属性。如果没有，该算法将源头的驼峰字母部分从右侧分割成一个头和一个尾，并试图找到相应的属性—​在我们的例子中，是 AddressZip 和 Code。如果该算法找到了具有该头部的属性，它就取其尾部，并从那里继续向下构建树，以刚才描述的方式将尾部分割开来。如果第一次分割不匹配，该算法将分割点移到左边（Address, ZipCode）并继续。

虽然这在大多数情况下应该是有效的，但该算法有可能选择错误的属性。假设 Person 类也有一个 addressZip 属性。该算法将在第一轮分割中已经匹配，选择错误的属性，并且失败（因为 addressZip 的类型可能没有 code 属性）。

为了解决这个模糊的问题，你可以在你的方法名里面使用 _ 来手动定义遍历点。因此，我们的方法名称将如下。

List findByAddress_ZipCode(ZipCode zipCode);

因为我们把下划线字符当作一个保留字符，所以我们强烈建议遵循标准的Java命名惯例（也就是说，不要在属性名中使用下划线，而要使用驼峰大写）。

8.4.4. 特殊参数处理

为了处理你的查询中的参数，定义方法参数，正如在前面的例子中已经看到的。除此之外，基础设施还能识别某些特定的类型，如 Pageable 和 Sort，以动态地将分页和排序应用于你的查询。下面的例子演示了这些功能。

Example 14. 在查询方法中使用 Pageable、Slice 和 Sort。

Page findByLastname(String lastname, Pageable pageable);

Slice findByLastname(String lastname, Pageable pageable);

List findByLastname(String lastname, Sort sort);

List findByLastname(String lastname, Pageable pageable);

API中定义的 Sort 和 Pageable 实际调用时不能为 null。如果你不想应用任何排序或分页，请使用 Sort.unsorted() 和 Pageable.unpaged()。

第一个方法让你把 org.springframework.data.domain.Pageable 实例传递给 query 方法，以动态地将分页添加到你静态定义的查询中。一个 Page 知道可用的元素和页面的总数。它是通过基础设施触发一个 count 查询来计算总数量。由于这可能是昂贵的（取决于使用的store），你可以返回一个 Slice。一个 Slice 只知道下一个 Slice 是否可用，当遍历一个较大的结果集时，这可能就足够了。

排序选项也是通过 Pageable 实例处理的。如果你只需要排序，在你的方法中加入 org.springframework.data.domain.Sort 参数。正如你所看到的，返回一个 List 也是可能的。在这种情况下，构建实际的 Page 实例所需的额外元数据并没有被创建（这反过来意味着不需要发出额外的 count 查询）。相反，它限制了查询，只查询给定范围的实体。

要想知道你 query 的总页数，你必须触发一个额外的count查询。默认情况下，这个查询是由你实际触发的查询派生出来的。

分页和排序

你可以通过使用属性名称来定义简单的排序表达式。你可以将表达式连接起来，将多个 criteria 收集到一个表达式中。

Example 15. Defining sort expressions

Sort sort = Sort.by("firstname").ascending()
  .and(Sort.by("lastname").descending());

对于定义排序表达式的更加类型安全的方式，从定义排序表达式的类型开始，使用方法引用来定义排序的属性。

Example 16. 通过使用类型安全的API来定义排序表达式

TypedSort person = Sort.sort(Person.class);

Sort sort = person.by(Person::getFirstname).ascending()
  .and(person.by(Person::getLastname).descending());

TypedSort.by(…​) 通过（通常）使用 CGlib 来使用运行时代理，这在使用 Graal VM Native 等工具时可能会干扰原生镜像的编译。

如果你的 store 实现支持 Querydsl，你也可以使用生成的 metamodel 类型来定义排序表达式。

Example 17. 通过使用Querydsl API定义排序表达式

QSort sort = QSort.by(QPerson.firstname.asc())
  .and(QSort.by(QPerson.lastname.desc()));

8.4.5. 限制查询结果

你可以通过使用 first 或 top 关键字来限制查询方法的结果，这两个关键字可以互换使用。你可以在 top 或 first 后面附加一个可选的数值，以指定要返回的最大结果大小。如果不加数字，就会假定结果大小为 1。下面的例子显示了如何限制查询的大小。

Example 18. 使用 Top 和 First 限制查询结果集

User findFirstByOrderByLastnameAsc();

User findTopByOrderByAgeDesc();

Page queryFirst10ByLastname(String lastname, Pageable pageable);

Slice findTop3ByLastname(String lastname, Pageable pageable);

List findFirst10ByLastname(String lastname, Sort sort);

List findTop10ByLastname(String lastname, Pageable pageable);

对于支持不同查询的数据集，限制表达式也支持 Distinct 关键字。另外，对于将结果集限制在一个实例的查询，支持用 Optional 关键字将结果包入。

如果分页或 slice 应用于 limit 查询的分页（以及可用页数的计算），则会在 limit 结果中应用。

通过使用 Sort 参数将结果与动态排序相结合，可以让你表达对 "K" 最小元素和 "K" 最大元素的查询方法。

8.4.6. Repository 方法返回 Collection 或 Iterable

返回多个结果的查询方法可以使用标准的Java Iterable、List 和 Set。除此之外，我们还支持返回Spring Data的 Streamable，这是 Iterable 的一个自定义扩展，以及 Vavr 提供的 collection 类型。请参考附录中对所有可能的 查询方法返回类型的解释。

使用 Streamable 作为 Query 方法的返回类型

你可以用 Streamable 来替代 Iterable 或任何 collection 类型。它提供了方便的方法来访问一个非并行的 Stream（Iterable 所没有的），并且能够在元素上直接 …​filter(…​) 和 …​map(…​)，并将 Streamable 与其他元素连接起来。

Example 19. 使用 Streamable 来组合 query 方法的结果

interface PersonRepository extends Repository {
  Streamable findByFirstnameContaining(String firstname);
  Streamable findByLastnameContaining(String lastname);
}

Streamable result = repository.findByFirstnameContaining("av")
  .and(repository.findByLastnameContaining("ea"));

返回自定义的 Streamable Wrapper 类型

为集合提供专用的 wrapper 类型是一种常用的模式，为返回多个元素的查询结果提供API。通常，这些类型的使用是通过调用返回类似集合类型的 repository 方法，并手动创建一个 wrapper 类型的实例。你可以避免这个额外的步骤，因为Spring Data允许你使用这些 wrapper 类型作为查询方法的返回类型，如果它们满足以下条件。

1. 该类型实现了 Streamable.
2. 该类型暴露了一个构造函数或一个名为 of(…​) 或 valueOf(…​) 的静态工厂方法，该方法将 Streamable 作为一个参数。

下面列出了一个例子。

class Product {                                         
  MonetaryAmount getPrice() { … }
}

@RequiredArgsConstructor(staticName = "of")
class Products implements Streamable {         

  private final Streamable streamable;

  public MonetaryAmount getTotal() {                    
    return streamable.stream()
      .map(Priced::getPrice)
      .reduce(Money.of(0), MonetaryAmount::add);
  }


  @Override
  public Iterator iterator() {                 
    return streamable.iterator();
  }
}

interface ProductRepository implements Repository {
  Products findAllByDescriptionContaining(String text); 
}

	一个 Product 实体，公开API以访问 product 的price。
	一个 Streamable 的封装类型，可以通过使用 Products.of(…​)（用Lombok注解创建的工厂方法）来构建。使用 Streamable 的标准构造函数也可以。
	wrapper 类型暴露了一个额外的API，在 Streamable 上计算新值。
	实现 Streamable 接口并委托给实际结果。
	wrapper 类型 Products 可以直接作为查询方法的返回类型。你不需要返回 Streamable 并在调用 repository 后手动封装它。

支持 Vavr 集合

Vavr 是一个拥抱Java中函数式编程概念的库。它带有一组自定义的集合类型，你可以将其作为查询方法的返回类型，如下表所示。

Vavr collection 类型	使用的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，以此类推。

8.4.7. Repository 方法的 Null 处理

从Spring Data 2.0开始，返回单个聚合实例的 repository CRUD方法使用Java 8的 Optional 来表示可能没有的值。除此之外，Spring Data还支持在查询方法上返回以下 wrapper 类型。

• com.google.common.base.Optional
• scala.Option
• io.vavr.control.Option

另外，查询方法可以选择完全不使用 wrapper 类型。没有查询结果的话会通过返回 null 来表示。Repository 方法返回集合、集合替代物、wrapper和流时，保证不会返回 null，而是返回相应的空（Empty）表示。详见 “Repository 查询返回类型”。

null约束注解

你可以通过使用 Spring Framework的nullability注解 来表达 repository 方法的 nullability 约束。它们提供了一种友好的方法，并在运行时选择加入 null 值检查，如下所示。

• @NonNullApi: 在 package 的层面上用于声明参数和返回值的默认行为，分别是既不接受也不产生 null 值。
• @NonNull: 用于不得为 null 的参数或返回值（不需要在参数和返回值中使用 @NonNullApi）。
• @Nullable: 用于可以是 null 的参数或返回值。

Spring注解是用 JSR 305 注解（一个休眠状态但广泛使用的JSR）进行元注解的。JSR 305元注解让工具供应商（如 IDEA、 Eclipse 和 Kotlin）以通用的方式提供 null-safety 支持，而不需要对Spring注解进行硬编码支持。为了在运行时检查查询方法的无效性约束，你需要通过在 package-info.java 中使用 Spring 的 @NonNullApi，在包级别上激活null约束，如下例所示。

Example 20. Declaring Non-nullability in package-info.java

@org.springframework.lang.NonNullApi
package com.acme;

一旦定义了非null约束，repository 的查询方法调用就会在运行时被验证是否有nul约束。如果查询结果违反了定义的约束条件，就会抛出一个异常。这种情况发生在方法会返回 null，但被声明为non-nullable（在 repository 所在的包上定义注解的默认值）。如果你想再次选择加入允许结果为null，可以有选择地在个别方法上使用 @Nullable。使用本节开头提到的结果wrapper类型继续按预期工作：一个空的结果被翻译成代表不存在的值。

下面的例子显示了刚才描述的一些技术。

Example 21. Using different nullability constraints

package com.acme;                                                       

interface UserRepository extends Repository {

  User getByEmailAddress(EmailAddress emailAddress);                    

  @Nullable
  User findByEmailAddress(@Nullable EmailAddress emailAdress);          

  Optional findOptionalByEmailAddress(EmailAddress emailAddress); 
}

	repository 在一个包（或子包）中，我们已经为其定义了非空的行为。
	当查询没有产生结果时，抛出一个 EmptyResultDataAccessException。当交给该方法的 emailAddress 为 null 时，抛出一个 IllegalArgumentException。
	当查询没有产生结果时返回 null。也接受 null 作为 emailAddress 的值。
	当查询没有产生结果时，返回 Optional.empty()。当交给该方法的 emailAddress 为 null 时，抛出一个 IllegalArgumentException。

基于Kotlin的 Repository 中的 Nullability

Kotlin在语言中加入了 对无效性约束的定义。Kotlin代码编译为字节码，它不通过方法签名来表达无效性约束，而是通过编译后的元数据。请确保在你的项目中包含 kotlin-reflect JAR，以实现对Kotlin的nullability约束的内省。Spring Data Repository 使用语言机制来定义这些约束，以应用相同的运行时检查，如下所示。

Example 22. Using nullability constraints on Kotlin repositories

interface UserRepository : Repository {

  fun findByUsername(username: String): User     

  fun findByFirstname(firstname: String?): User? 
}

	该方法将参数和结果都定义为不可为空（Kotlin默认）。Kotlin编译器会拒绝那些向方法传递 null 的方法调用。如果查询产生了一个空的结果，就会抛出一个 EmptyResultDataAccessException。
	这个方法接受 null 作为 firstname 参数，如果查询没有产生结果，则返回 null。

8.4.8. 流式（Stream）查询结果

你可以通过使用Java 8 Stream 作为返回类型来增量地处理查询方法的结果。如下面的例子所示，不把查询结果包裹在 Stream 中，而是使用 data store 的特定方法来执行流式处理。

Example 23. Stream the result of a query with Java 8 Stream

@Query("select u from User u")
Stream findAllByCustomQueryAndStream();

Stream readAllByFirstnameNotNull();

@Query("select u from User u")
Stream streamAllPaged(Pageable pageable);

一个 Stream 可能包裹了底层 data store 的特定资源，因此，在使用后必须关闭。你可以通过使用 close() 方法来手动关闭 Stream，或者使用Java 7 try-with-resources 块来关闭，如下面的例子中所示。

Example 24. Working with a Stream result in a try-with-resources block

try (Stream stream = repository.findAllByCustomQueryAndStream()) {
  stream.forEach(…);
}

目前并非所有的Spring Data模块都支持 Stream 作为返回类型。

8.4.9. 异步（Asynchronous）查询结果

你可以通过使用 Spring的异步方法运行能力 来异步运行 repository 查询。这意味着该方法在调用后立即返回，而实际的查询发生在一个已经提交给Spring TaskExecutor 的任务中。异步查询与响应式查询不同，不应混合使用。关于响应式支持的更多细节，请参见store的特定文档。下面的例子显示了一些异步查询的案例。

@Async
Future findByFirstname(String firstname);               

@Async
CompletableFuture findOneByFirstname(String firstname); 

	使用 java.util.concurrent.Future 作为返回类型。
	使用 Java 8 java.util.concurrent.CompletableFuture 作为返回类型。

8.5. 创建 Repository 实例

本节介绍了如何为定义的 repository 接口创建实例和Bean定义。

8.5.1. Java 配置

在Java配置类上使用store特有的 @EnableMongoRepositories 注解来定义 repository 激活的配置。关于基于Java的Spring容器配置的介绍，请参见 Spring参考文档中的JavaConfig。

启用 Spring Data Repository 的示例配置类似于以下内容。

Example 25. 基于注解的 repository 配置示例

@Configuration
@EnableJpaRepositories("com.acme.repositories")
class ApplicationConfiguration {

  @Bean
  EntityManagerFactory entityManagerFactory() {
    // …
  }
}

前面的例子使用了JPA特定的注解，你可以根据你实际使用的store模块来改变它。这同样适用于 EntityManagerFactory Bean的定义。请看涉及store特定配置的章节。

8.5.2. XML 配置

每个Spring Data模块都包括一个 repositories 元素，让你定义一个Spring为你扫描的 base package，如下例所示。

Example 26. 通过XML启用Spring Data Repository

在前面的例子中，Spring被指示扫描 com.acme.repositories 及其所有子包，以寻找扩展 Repository 或其子接口之一的接口。对于找到的每个接口，基础设施都会注册持久化技术专用的 FactoryBean，以创建适当的代理，处理查询方法的调用。每个Bean都被注册在一个从接口名称衍生出来的Bean名称下，所以 UserRepository 的接口将被注册在 userRepository 下。嵌套的存储库接口的Bean名是以其包裹的类型名称为前缀。base package 属性允许通配符，这样你就可以定义一个扫描包的模式。

8.5.3. 使用 Filter

默认情况下，基础架构会抓取每个扩展了位于配置的 base package 下的持久化技术特定的 Repository 子接口的接口，并为其创建一个Bean实例。然而，你可能想要更精细地控制哪些接口为其创建Bean实例。要做到这一点，可以在 Repository 声明中使用 filter 元素。其语义与Spring的组件过滤器中的元素完全等同。详情请见 Spring参考文档 中的这些元素。

例如，为了排除某些接口作为 Repository Bean 的实例化，你可以使用以下配置。

Example 27. 使用 Filter

Java

XML

@Configuration
@EnableMongoRepositories(basePackages = "com.acme.repositories",
    includeFilters = { @Filter(type = FilterType.REGEX, pattern = ".*SomeRepository") },
    excludeFilters = { @Filter(type = FilterType.REGEX, pattern = ".*SomeOtherRepository") })
class ApplicationConfiguration {

  @Bean
  EntityManagerFactory entityManagerFactory() {
    // …
  }
}

前面的例子排除了所有以 SomeRepository 结尾的接口被实例化，包括以 SomeOtherRepository 结尾的接口。

8.5.4. 单独使用

你也可以在Spring容器之外使用资源库基础设施—​例如，在CDI环境中。你仍然需要在你的classpath中使用一些Spring库，但是，一般来说，你也可以通过编程来设置 Repository。Repository 支持的Spring Data模块都有一个特定于持久化技术的 RepositoryFactory，你可以使用，如下所示。

Example 28. repository factory 的独立使用

RepositoryFactorySupport factory = … // Instantiate factory here
UserRepository repository = factory.getRepository(UserRepository.class);

8.6. 自定义 Spring Data Repository 的实现

Spring Data提供了各种选项来创建查询方法，只需少量编码。但当这些选项不符合你的需求时，你也可以为 repository 方法提供你自己的自定义实现。本节介绍了如何做到这一点。

8.6.1. 自定义个别 Repository

要用自定义的功能来丰富 repository，你必须首先定义一个片段（fragment）接口和自定义功能的实现，如下所示。

Example 29. 定制 repository 功能的接口

interface CustomizedUserRepository {
  void someCustomMethod(User user);
}

Example 30. 实现自定义 repository 的功能

class CustomizedUserRepositoryImpl implements CustomizedUserRepository {

  public void someCustomMethod(User user) {
    // Your custom implementation
  }
}

与片段接口对应的类名中最重要的部分是 Impl 后缀。

实现本身并不依赖于Spring Data，它可以是一个普通的Spring Bean。因此，你可以使用标准的依赖注入行为来注入对其他Bean（如 JdbcTemplate）的引用，参与到各个切面，等等。

然后你可以让你的 repository 接口继承片段接口，如下所示。

Example 31. 改变你的 repository 接口

interface UserRepository extends CrudRepository, CustomizedUserRepository {

  // Declare query methods here
}

用你的存储库接口继承片段接口，结合了CRUD和自定义功能，并使其对客户端可用。

Spring Data Repository 是通过使用形成 repository 组合的片段来实现的。片段是基础repository、功能方面（如 QueryDsl），以及自定义接口和它们的实现。每当你为你的repository接口添加一个接口，你就通过添加一个片段来增强组合。基础repository和repository方面的实现是由每个Spring Data模块提供的。

下面的例子显示了自定义接口和它们的实现。

Example 32. 片段及其实现

interface HumanRepository {
  void someHumanMethod(User user);
}

class HumanRepositoryImpl implements HumanRepository {

  public void someHumanMethod(User user) {
    // Your custom implementation
  }
}

interface ContactRepository {

  void someContactMethod(User user);

  User anotherContactMethod(User user);
}

class ContactRepositoryImpl implements ContactRepository {

  public void someContactMethod(User user) {
    // Your custom implementation
  }

  public User anotherContactMethod(User user) {
    // Your custom implementation
  }
}

下面的例子显示了一个扩展了 CrudRepository 的自定义 repository 的接口。

Example 33. 修改你的 repository 接口

interface UserRepository extends CrudRepository, HumanRepository, ContactRepository {

  // Declare query methods here
}

Repository可以由多个自定义实现组成，这些自定义实现按其声明的顺序被导入。自定义实现的优先级高于基础实现和Repository 切面。这种排序可以让你覆盖基础Repository和切面的方法，并在两个片段贡献了相同的方法签名时解决歧义。Repository片段不限于在单一存储库接口中使用。多个Repository可以使用一个片段接口，让你在不同的 Repository 中重复使用自定义的内容。

下面的例子显示了一个 Repository 片段及其实现。

Example 34. Fragments overriding save(…)

interface CustomizedSave {
   S save(S entity);
}

class CustomizedSaveImpl implements CustomizedSave {

  public  S save(S entity) {
    // Your custom implementation
  }
}

下面的例子显示了一个使用前述 repository 片段的 repository。

Example 35. 自定义 repository 接口

interface UserRepository extends CrudRepository, CustomizedSave {
}

interface PersonRepository extends CrudRepository, CustomizedSave {
}

配置

repository基础设施试图通过扫描发现repository的包下面的类来自动检测自定义实现片段。这些类需要遵循后缀默认为 Impl 的命名惯例。

下面的例子显示了一个使用默认后缀的 repository 和一个为后缀设置了自定义值的 repository。

Example 36. 配置示例

Java

XML

@EnableMongoRepositories(repositoryImplementationPostfix = "MyPostfix")
class Configuration { … }

前面例子中的第一个配置试图查找一个叫做 com.acme.repository.CustomizedUserRepositoryImpl 的类，作为一个自定义的 repository 实现。第二个例子试图查找 com.acme.repository.CustomizedUserRepositoryMyPostfix。

消除歧义

如果在不同的包中发现了具有匹配类名的多个实现，Spring Data会使用Bean名称来确定使用哪一个。

考虑到前面显示的 CustomizedUserRepository 的以下两个自定义实现，第一个实现被使用。它的Bean名是 customedUserRepositoryImpl，与片段接口（CustomizedUserRepository）加后缀 Impl 的名字一致。

Example 37. 解决模棱两可的实现

package com.acme.impl.one;

class CustomizedUserRepositoryImpl implements CustomizedUserRepository {

  // Your custom implementation
}

package com.acme.impl.two;

@Component("specialCustomImpl")
class CustomizedUserRepositoryImpl implements CustomizedUserRepository {

  // Your custom implementation
}

If you annotate the UserRepository interface with @Component("specialCustom"), the bean name plus Impl then matches the one defined for the repository implementation in com.acme.impl.two, and it is used instead of the first one.

如果你用 @Component("specialCustom") 来注解 UserRepository 接口，那么Bean名加 Impl 就会与 com.acme.impl.two 中为repository实现定义的豆名相匹配，并被用来替代第一个豆名。

手动注入

如果你的自定义实现只使用基于注解的配置和自动注入，前面所示的方法很好用，因为它被当作任何其他Spring Bean。如果你的实现片段Bean需要特殊的注入，你可以根据前文所述的约定来声明Bean并为其命名。然后，基础设施通过名称来引用手动定义的Bean定义，而不是自己创建一个。下面的例子展示了如何手动注入一个自定义的实现。

Example 38. 手动注入一个自定义实现

Java

XML

class MyClass {
  MyClass(@Qualifier("userRepositoryImpl") UserRepository userRepository) {
    …
  }
}

8.6.2. 自定义 Base Repository

当你想定制基础 repository 的行为时，上一节描述的方法需要定制每个 repository 的接口，以便所有的 repository 都受到影响。为了改变所有 repository 的行为，你可以创建一个扩展持久化技术特定 repository 基类的实现。然后这个类作为 repository 代理的自定义基类，如下面的例子所示。

Example 39. 自定义 repository base 类

class MyRepositoryImpl
  extends SimpleJpaRepository {

  private final EntityManager entityManager;

  MyRepositoryImpl(JpaEntityInformation entityInformation,
                          EntityManager entityManager) {
    super(entityInformation, entityManager);

    // Keep the EntityManager around to used from the newly introduced methods.
    this.entityManager = entityManager;
  }

  @Transactional
  public  S save(S entity) {
    // implementation goes here
  }
}

该类需要有一个super类的构造器，store特定的 repository factory 实现使用该构造器。如果repository 基类有多个构造函数，请复写其中一个构造函数，该构造函数需要一个 EntityInformation 和一个store特定的基础设施对象（如 EntityManager 或模板类）。

最后一步是让Spring Data基础设施意识到定制的 repository base 类。在配置中，你可以通过使用 repositoryBaseClass 来做到这一点，如下面的例子所示。

Example 40. 配置一个自定义 repository base 类

Java

XML

@Configuration
@EnableMongoRepositories(repositoryBaseClass = MyRepositoryImpl.class)
class ApplicationConfiguration { … }

8.7. 从 Aggregate Root （聚合ROOT）中发布事件

由 Repository 管理的实体是 aggregate root。在领域驱动设计应用程序中，这些aggregate root通常会发布 domain 事件。Spring Data提供了一个名为 @DomainEvents 的注解，你可以在 aggregate root 的一个方法上使用该注解，以使这种发布尽可能地简单，如下例所示。

Example 41. 从aggregate root中暴露domain 事件

class AnAggregateRoot {

    @DomainEvents 
    Collection