Spring Data JDBC（二）

Spring Data JDBC - Reference Documentation

https://docs.spring.io/spring-data/jdbc/docs/1.0.6.RELEASE/reference/html/

前言

Spring Data JDBC提供基于JDBC的存储库抽象。

项目元数据

• 版本控制: http://github.com/spring-projects/spring-data-jdbc

• 错误追踪系统: https://jira.spring.io/browse/DATAJDBC

• 发布存储库: https://repo.spring.io/libs-release

• 里程碑存储库: https://repo.spring.io/libs-milestone

• 快照存储库: https://repo.spring.io/libs-snapshot

1. 新的和值得注意的

本节介绍每个版本的重大更改。

1.1. Spring Data JDBC 1.0中有什么新功能

• Basic support for CrudRepository. 对CrudRepository的基本支持。

• @Query support.@Query支持。

• MyBatis support.MyBatis支持。

• Id generation.Id代。

• Event support. 事件支持。

• Auditing.审计。

• CustomConversions.自定义转换。

2. 依赖

由于各个Spring Data模块的创建日期不同，因此大多数模块都带有不同的主要版本号和次要版本号。找到兼容版本的最简单方法是依靠Spring Data Release Train BOM，它是我们为了处理版本兼容而定义的。在Maven项目中，您需要在POM的部分中声明此依赖项，如下所示：

Example 1. Using the Spring Data release train BOM

  
    
      org.springframework.data
      spring-data-releasetrain
      Lovelace-SR6
      import
      pom
    
  

目前的发布版本是Lovelace-SR6。列车名称按字母顺序上升，此处列出了当前可用的列车。版本名称遵循以下模式：$ {name}  -  $ {release}，其中release可以是以下之一：

• BUILD-SNAPSHOT: 当前快照

• M1, M2, and so on: 里程碑

• RC1, RC2, and so on: 发布候选版

• RELEASE: GA发布

• SR1, SR2, 等等：服务发布版

可以在我们的Spring Data示例存储库中找到使用BOM的工作示例。有了这个，您可以在块中声明要使用的Spring Data模块并且不需要指定具体版本，如下所示：

示例2.声明对Spring Data模块的依赖关系

  
    org.springframework.data
    spring-data-jpa
  

2.1. Spring Boot的依赖管理

Spring Boot为您选择最新版本的Spring Data模块。如果您仍想升级到更新版本，请将属性spring-data-releasetrain.version配置为您要使用的列车名称和迭代。

2.2. Spring 框架

当前版本的Spring Data模块需要版本5.1.6.RELEASE或更高版本的Spring Framework。这些模块也可以使用该次要版本的旧版本。但是，强烈建议使用该代中的最新版本。

3. 使用Spring Data Repositories

Spring Data存储库抽象的目标是显着减少为各种持久性存储实现数据访问层所需的样板代码量。

Spring Data存储库文档和您的模块 本章介绍Spring Data存储库的核心概念和接口。本章中的信息来自Spring Data Commons模块。它使用Java Persistence API（JPA）模块的配置和代码示例。您应该将XML名称空间声明和要扩展的类型调整为您使用的特定模块的等效项。“命名空间参考”涵盖XML配置，支持存储库API的所有Spring Data模块都支持XML配置。“存储库查询关键字”涵盖了存储库抽象支持的查询方法关键字。有关模块特定功能的详细信息，请参阅本文档该模块的章节。

3.1. 核心概念

Spring Data存储库抽象中的中央接口是Repository。它将域类以及域类的ID类型作为类型参数进行管理。此接口主要用作标记接口，用于捕获要使用的类型，并帮助您发现扩展此接口的接口。CrudRepository为正在管理的实体类提供复杂的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的实体。

我们还提供特定的持久性技术的抽象，例如JpaRepository或MongoRepository。除了相当通用的持久性技术无关的接口（如CrudRepository）之外，这些接口还扩展了CrudRepository并公开了底层持久性技术的功能。

在CrudRepository之上，有一个PagingAndSortingRepository抽象，它添加了额外的方法来简化对实体的分页访问：

Example 4. PagingAndSortingRepository 接口

public interface PagingAndSortingRepository extends CrudRepository {

  Iterable findAll(Sort sort);

  Page findAll(Pageable pageable);
}

要以20的页面大小访问User的第二页，您可以执行以下操作：

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

除了查询方法之外，还可以使用计数和删除查询的查询派生。以下列表显示派生计数查询的接口定义：

Example 5. 派生计数查询

interface UserRepository extends CrudRepository {

  long countByLastname(String lastname);
}

以下列表显示了派生删除查询的接口定义：

Example 6. 派生删除查询

interface UserRepository extends CrudRepository {

  long deleteByLastname(String lastname);

  List removeByLastname(String lastname);
}

3.2. 查询方法

标准CRUD功能存储库通常对基础数据存储区进行查询。使用Spring Data，声明这些查询将分为四个步骤：

1. 声明扩展Repository或其子接口之一的接口，并将其键入应处理的域类和ID类型，如以下示例所示：

   interface PersonRepository extends Repository { … }

2. 在接口上声明查询方法。

   interface PersonRepository extends Repository {
     List findByLastname(String lastname);
   }

3. 设置Spring以使用JavaConfig或XML配置，为这些接口创建代理实例。

   1. 要使用Java配置，请创建类似于以下内容的类：

      import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
      
      @EnableJpaRepositories
      class Config { … }

   2. 要使用XML配置，请创建类似于以下内容的类：

   在此示例中使用JPA名称空间。如果对任何其他存储使用存储库抽象，则需要将其更改为存储模块的相应名称空间声明。换句话说，你应该交换jpa，例如mongodb。

   repository’s @Enable${store}Repositories-annotation.+另外，请注意JavaConfig变体不会显式配置包，因为默认情况下使用带注释的类的包。要自定义要扫描的包，请使用特定于数据存储库的@ Enable $ {store}存储库注释的basePackage ...属性之一。

4. 注入存储库实例并使用它，如以下示例所示：

   class SomeClient {
   
     private final PersonRepository repository;
   
     SomeClient(PersonRepository repository) {
       this.repository = repository;
     }
   
     void doSomething() {
       List persons = repository.findByLastname("Matthews");
     }
   }

以下部分详细说明了每个步骤：

• 定义存储库接口

• 定义查询方法

• 创建存储库实例

• 自定义实现Spring Data Repositories

3.3. 定义存储卡接口

首先，定义特定域类的存储库接口。接口必须扩展Repository并键入域类和ID类型。如果要公开该域类型的CRUD方法，请扩展CrudRepository而不是Repository。

3.3.1. 微调存储库定义

通常，存储库接口扩展了Repository，CrudRepository或PagingAndSortingRepository。另外，如果您不想扩展Spring Data接口，还可以使用@RepositoryDe​​finition注释存储库接口。扩展CrudRepository公开了一整套操作实体的方法。如果您更愿意选择要公开的方法，请将要从CrudRepository公开的方法复制到域存储库中。

这样做可以让您在提供的Spring Data Repositories功能之上定义自己的抽象。

以下示例显示如何有选择地公开CRUD方法（在本例中为findById和save）：

Example 7. 选择性暴露CRUD方法

@NoRepositoryBean
interface MyBaseRepository extends Repository {

  Optional findById(ID id);

   S save(S entity);
}

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

在前面的示例中，您为所有域存储库定义了一个公共基本接口，并公开了findById（...）以及save（...）。这些方法被路由到Spring Data提供的所选存储的基本存储库实现中（例如，如果您使用JPA，则实现是SimpleJpaRepository），因为它们与CrudRepository中的方法签名匹配。因此，UserRepository现在可以保存用户，按ID查找单个用户，并触发查询以通过电子邮件地址查找用户。

中间存储库接口使用@NoRepositoryBean注释。确保将该注释添加到那些在Spring Data运行时无需创建实例的存储库接口上。

3.3.2. 使用具有多个Spring数据模块的存储库

在应用程序中使用唯一的Spring Data模块会使事情变得简单，因为定义范围内的所有存储库接口都绑定到Spring Data模块。有时，应用程序需要使用多个Spring Data模块。在这种情况下，存储库定义必须区分持久性技术。当它在类路径上检测到多个存储库工厂时，Spring Data进入严格的存储库配置模式。严格配置使用存储库或域类的详细信息来确定存储库定义的Spring Data模块绑定：

1. 如果存储库定义扩展了特定模块的存储库，那么它是特定Spring Data模块的有效候选者。

2. 如果使用特定模块的类型注释对域类进行注释，则它是特定Spring Data模块的有效候选者。Spring Data模块接受第三方注释（例如JPA的@Entity）或提供自己的注释（例如Spring Data MongoDB和Spring Data Elasticsearch的@Document）。

以下示例显示了使用特定模块的接口的存储库（在本例中为JPA）：

Example 8. 使用特定模块的接口的存储库定义

interface MyRepository extends JpaRepository { }

@NoRepositoryBean
interface MyBaseRepository extends JpaRepository { … }

interface UserRepository extends MyBaseRepository { … }

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

以下示例显示了使用通用接口的存储库：

Example 9. 使用通用接口的存储库定义

interface AmbiguousRepository extends Repository { … }

@NoRepositoryBean
interface MyBaseRepository extends CrudRepository { … }

interface AmbiguousUserRepository extends MyBaseRepository { … }

AmbiguousRepository和AmbiguousUserRepository仅在其类型层次结构中扩展Repository和CrudRepository。虽然这在使用独特的Spring Data模块时非常好，但是多个模块无法区分这些存储库应该绑定到哪个特定的Spring Data。

以下示例显示了使用带注释的域类的存储库：

Example 10. 使用带注释的域类的存储库定义

interface PersonRepository extends Repository { … }

@Entity
class Person { … }

interface UserRepository extends Repository { … }

@Document
class User { … }

PersonRepository引用Person，它使用JPA @Entity批注进行批注，因此该存储库显然属于Spring Data JPA。UserRepository引用User，它使用Spring Data MongoDB的@Document注释进行注释。

以下错误示例显示了使用具有混合注释的域类的存储库：

Example 11. 使用具有混合注释的域类的存储库定义

interface JpaPersonRepository extends Repository { … }

interface MongoDBPersonRepository extends Repository { … }

@Entity
@Document
class Person { … }

此示例显示了使用JPA和Spring Data MongoDB注释的域类。它定义了两个存储库，JpaPersonRepository和MongoDBPersonRepository。一个用于JPA，另一个用于MongoDB用法。Spring Data不再能够将存储库分开，从而导致未定义的行为。

存储库类型详细信息和区分域类注释用于严格存储库配置，以识别特定Spring数据模块的存储库候选。在同一域类型上使用多个持久性技术特定的注释是可能的，并允许跨多种持久性技术重用域类型。但是，Spring Data不再能够确定用于绑定存储库的唯一模块。

区分存储库的最后一种方法是通过确定存储库基础包的范围。基础包定义了扫描存储库接口定义的起点，这意味着将存储库定义放在相应的包中。默认情况下，注释驱动的配置使用配置类的包。基于XML的配置中的基础包是必需的。

以下示例显示了基本包的注释驱动配置：

Example 12. 基础包的注释驱动配置

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

3.4. Defining Query Methods

存储库代理有两种方法可以从方法名称派生特定存储的查询：

• 通过直接从方法名称派生查询。

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

可用选项取决于实际存储。但是，必须有一个策略来决定创建实际查询的内容。下一节将介绍可用选项。

3.4.1. 查询查找策略

存储库基础结构可以使用以下策略来解析查询。使用XML配置，您可以通过query-lookup-strategy属性在命名空间配置策略。对于Java配置，您可以使用Enable $ {store}Repositories 注释的queryLookupStrategy属性。特定数据存储可能不支持某些策略。

• CREATE 尝试从查询方法名称构造特定存储的查询。一般方法是从方法名称中删除一组已知的前缀，并解析方法的其余部分。您可以在“创建查询”中阅读有关查询构造的更多信息。

• USE_DECLARED_QUERY 尝试查找声明的查询，如果找不到，则抛出异常。查询可以通过某处的注释来定义，也可以通过其他方式声明。查阅特定存储的文档以查找该存储​​的可用选项。如果存储库基础结构在引导时未找到该方法的声明查询，则它将失败。

• CREATE_IF_NOT_FOUND （默认）结合CREATE和USE_DECLARED_QUERY。它首先查找声明的查询，如果没有找到声明的查询，它会创建一个基于自定义方法名称的查询。这是默认的查找策略，因此，如果您未明确配置任何内容，则使用此策略。它允许通过方法名称进行快速查询定义，还可以根据需要引入声明的查询来自定义这些查询。

3.4.2. 创建查询

Spring Data存储库基础结构中内置的查询构建器机制对于构建存储库实体的约束查询非常有用。该机制从方法名称中剥离前缀find ... By，read ... By，query ... By，count ... By，and get ...并开始解析其余部分。introduction子句可以包含更多表达式，例如Distinct在要创建的查询上设置不同的标志。但是，第一个By用作分隔符以指示实际条件的开始。在最基本的层面上，您可以在实体属性上定义条件，并将它们与And和Or连接起来。以下示例显示了如何创建大量查询：

Example 13. 从方法名称创建查询

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);
}

解析方法的实际结果取决于您为其创建查询的持久性存储。但是，有一些一般要注意的事项：

• 表达式通常是属性遍历与可以连接的运算符相结合。您可以将属性表达式与AND和OR组合在一起。对于属性表达式，您还可以获得诸如Between，LessThan，GreaterThan和Like之类的运算符。支持的运算符可能因数据存储而异，因此请参阅参考文档的相应部分。

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

• 您可以通过将OrderBy子句附加到引用属性的查询方法并提供排序方向（Asc或Desc）来应用静态排序。要创建支持动态排序的查询方法，请参阅“特殊参数处理”。

3.4.3. 属性表达式

属性表达式只能引用被托管实体的直接属性，如前面的示例所示。在创建查询时，您已确保已解析的属性是托管域类的属性。但是，您也可以通过遍历嵌套属性来定义约束。请考虑以下方法签名：

List findByAddressZipCode(ZipCode zipCode);

假设一个人有一个带ZipCode的地址。在这种情况下，该方法创建属性遍历x.address.zipCode。解析算法首先将整个部分（AddressZipCode）解释为属性，并检查域类中是否具有该名称的属性（未大写）。如果算法成功，它将使用该属性。如果没有，算法将来自右侧的驼峰案例部分的源分成头部和尾部，并尝试找到相应的属性 - 在我们的示例中，AddressZip和Code。如果算法找到具有该头部的属性，则它采用尾部并继续从那里构建树，以刚刚描述的方式将尾部分开。如果第一个分割不匹配，算法会将分割点移动到左侧（Address，ZipCode）并继续。

虽然这应该适用于大多数情况，但算法可能会选择错误的属性。假设Person类也有一个addressZip属性。算法将在第一个拆分轮中匹配，选择错误的属性，并失败（因为addressZip的类型可能没有代码属性）。

要解决这种歧义，可以在方法名称中使用_来手动定义遍历点。所以我们的方法名称如下：

List findByAddress_ZipCode(ZipCode zipCode);

因为我们将下划线字符视为保留字符，所以我们强烈建议遵循标准Java命名约定（即，不在属性名称中使用下划线，而是使用camel case）。

3.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);

第一种方法允许您将org.springframework.data.domain.Pageable实例传递给查询方法，以动态地向您的静态定义查询添加分页。page知道可用元素和页面的总数。它通过基础设施触发计数查询来计算总数来实现。由于这可能很昂贵（取决于所使用的存储），您可以改为返回切片。Slice只知道下一个Slice是否可用，这在遍历更大的结果集时可能就足够了。

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

要了解整个查询的页数，必须触发其他计数查询。默认情况下，此查询是从您实际触发的查询派生的。

3.4.5. 限制查询结果

查询方法的结果可以通过使用first或top关键字来限制，这些关键字可以互换使用。可选的数值可以附加到top或first，以指定要返回的最大结果大小。如果省略该数字，则假定结果大小为1。以下示例显示如何限制查询大小：

Example 15. 使用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关键字将结果包装。

如果将分页或切片应用于限制查询分页（以及可用页数的计算），则将其应用于有限结果中。

通过使用Sort参数将结果与动态排序结合，让您实现“K”个最小元素以及“K”个最大元素的查询方法。

3.4.6. 存储库方法返回集合或迭代类型

返回多个结果的查询方法可以使用标准Java Iterable，List，Set。除此之外，我们支持返回Spring Data的Streamable，Iterable的自定义扩展，以及Vavr提供的集合类型。

使用Streamable作为查询方法返回类型

Streamable可以用作Iterable或任何集合类型的替代品。它提供了方便的方法来访问非并行Stream（从Iterable中丢失），直接... .filter（...）和... .map（...）在元素上的能力，并将Streamable连接到其他人：

Example 16. 使用Streamable组合查询方法结果

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

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

返回自定义流式包装类型

为集合提供专用包装类型是一种常用模式，用于在返回多个元素的查询执行结果上提供API。 通常，这些类型通过调用存储库方法来使用，该方法返回类似集合的类型并手动创建包装类型的实例。 可以避免这个额外的步骤，因为Spring Data允许使用这些包装类型作为查询方法返回类型，如果它们满足以下标准：

1. 该类型实现了Streamable。

2. 该类型公开构造函数或名为（...）的静态工厂方法或以Streamable为参数的valueOf（...）。

示例用例如下所示：

class Product { 
  MonetaryAmount getPrice() { … }
}

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

  private Streamable streamable;

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

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

	公开API以访问产品价格的产品实体。
	Streamable 的包装类型，可以通过Products.of（...）构建（通过Lombok注释创建的工厂方法）。
	包装器类型在Streamable 上公开了额外的API计算新值。
	该包装类型可以直接用作查询方法返回类型。无需返回Stremable 并手动将其包装在存储库客户端中。

支持Vavr集合

Vavr是一个用Java包含函数式编程概念的库。它附带了一组自定义集合类型，可用作查询方法返回类型。

Vavr collection type	Used Vavr implementation type	Valid Java source types
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变为VavrLinkedHashSet / Set等。

3.4.7. 存储库方法的NULL处理

从Spring Data 2.0开始，返回单个聚合实例的存储库CRUD方法使用Java 8的Optional来指示可能缺少值。除此之外，Spring Data支持在查询方法上返回以下包装类型：

• com.google.common.base.Optional

• scala.Option

• io.vavr.control.Option

或者，查询方法可以选择根本不使用包装类型。然后通过返回null来指示缺少查询结果。存储库方法确保返回集合，集合替代，包装器和流，且永远不会返回null，而是返回相应的空表示。有关详细信息，请参阅“存储库查询返回类型”。

可空性注释

您可以使用Spring Framework的可空性注释来表达存储库方法的可空性约束。它们在运行时提供了一种工具友好的方法和opt-in null检查，如下所示：

• @NonNullApi: 在包级别上使用，以声明参数和返回值的默认行为是不接受或生成空值

• @NonNull: 用于不能为null的参数或返回值（对于@NonNullApi适用的参数和返回值不需要）。

• @Nullable: 用于可以为null的参数或返回值。

Spring注释是使用JSR 305注释进行元注释的（一种休眠但广泛传播的JSR）。JSR 305元注释允许IDEA，Eclipse和Kotlin等工具供应商以通用方式提供空安全支持，而无需对Spring注释进行硬编码支持。要为查询方法启用运行时检查可空性约束，需要在package-info.java中使用Spring的@NonNullApi来激活包级别的非可空性，如以下示例所示：

Example 17. 在package-info.java中声明不可为空性

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

一旦存在非null默认值，就会在运行时验证存储库查询方法调用的可空性约束。如果查询执行结果违反了定义的约束，则抛出异常。当方法返回null但声明为非可空（默认情况下，在存储库所在的包中定义了注释）时会发生这种情况。如果您想再次选择可以为空的结果，请在各个方法上有选择地使用@Nullable。使用本节开头提到的结果包装器类型将继续按预期工作：空结果将转换为表示缺席的值。

以下示例显示了刚才描述的一些技术：

Example 18. 使用不同的可空性约束

package com.acme;                                                       

import org.springframework.lang.Nullable;

interface UserRepository extends Repository {

  User getByEmailAddress(EmailAddress emailAddress);                    

  @Nullable
  User findByEmailAddress(@Nullable EmailAddress emailAdress);          

  Optional findOptionalByEmailAddress(EmailAddress emailAddress); 
}

	存储库驻留在我们已定义非空行为的包（或子包）中。
	当执行的查询未产生结果时，抛出EmptyResultDataAccessException。当传递给方法的emailAddress为null时，抛出IllegalArgumentException。
	当执行的查询未产生结果时返回null。同时接受null作为emailAddress的值。
	当执行的查询未产生结果时，返回Optional.empty（）。当传递给方法的emailAddress为null时，抛出IllegalArgumentException。

基于Kotlin的存储库中的可空性

Kotlin对语言中的可空性约束进行了定义。Kotlin代码编译为字节码，它不通过方法签名表达可空性约束，而是通过编译元数据表达。确保在项目中包含kotlin-reflect JAR，以便对Kotlin的可空性约束进行内省。Spring Data存储库使用语言机制来定义这些约束以应用相同的运行时检查，如下所示：

Example 19. 对Kotlin存储库使用可空性约束

interface UserRepository : Repository {

  fun findByUsername(username: String): User     

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

	该方法将参数和结果都定义为非可空（Kotlin默认值）。Kotlin编译器拒绝将null传递给方法的方法调用。如果查询执行产生空结果，则抛出EmptyResultDataAccessException。
	此方法对firstname参数接受null，如果查询执行不生成结果，则返回null。

3.4.8. 流式查询结果

可以使用Java 8 Stream 作为返回类型以递增方式处理查询方法的结果。而不是将查询结果包装在Stream中，数据存储特定的方法用于执行流式处理，如以下示例所示：

Example 20. 使用Java 8 Stream 流式传输查询结果

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

Stream readAllByFirstnameNotNull();

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

Stream可能会包装基础数据存储特定的资源，因此必须在使用后关闭。您可以使用close（）方法或使用Java 7 try-with-resources块手动关闭Stream，如以下示例所示：

Example 21. 使用Stream 会导致try-with-resources块

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

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

3.4.9. 异步查询结果

可以使用Spring的异步方法执行功能异步运行存储库查询。这意味着该方法在调用时立即返回，而实际的查询执行发生在已提交给Spring TaskExecutor的任务中。异步查询执行与反应式查询执行不同，不应混合使用。有关反应支持的更多详细信息，请参阅特定于存储的文档。以下示例显示了许多异步查询：

@Async
Future findByFirstname(String firstname);               

@Async
CompletableFuture findOneByFirstname(String firstname); 

@Async
ListenableFuture findOneByLastname(String lastname);    

	Use java.util.concurrent.Future 作为返回类型。
	Use a Java 8 java.util.concurrent.CompletableFuture 作为返回类型。
	Use a org.springframework.util.concurrent.ListenableFuture 作为返回类型。

3.5. 创建存储库实例

在本节中，您将为定义的存储库接口创建实例和bean定义。一种方法是使用随每个支持存储库机制的Spring Data模块一起提供的Spring命名空间，尽管我们通常建议使用Java配置。

3.5.1. XML配置

每个Spring Data模块都包含一个存储库元素，允许您定义Spring为您扫描的基础包，如以下示例所示：

Example 22. 通过XML启用Spring Data存储库

在前面的示例中，指示Spring扫描com.acme.repositories及其所有子包，以查找扩展Repository或其子接口的接口。对于找到的每个接口，基础结构都会注册特定于持久性技术的FactoryBean，以创建处理查询方法调用的相应代理。每个bean都是在从接口名称派生的bean名称下注册的，因此UserRepository的接口将在userRepository下注册。base-package属性允许使用通配符，以便您可以定义扫描包的模式。

使用过滤器

默认情况下，基础结构会选择扩展位于已配置的基础包下的特定于持久性技术的Repository子接口的每个接口，并为其创建一个bean实例。但是，您可能希望对哪些接口为其创建bean实例进行更细粒度的控制。为此，请在元素中使用和元素。语义完全等同于Spring的上下文命名空间中的元素。有关详细信息，请参阅这些元素的Spring参考文档。

例如，要将某些接口从实例化中排除为存储库bean，可以使用以下配置：示例23.

Example 23. 使用exclude-filter元素

前面的示例排除了以SomeRepository结尾的所有接口的实例化。

3.5.2. Java配置

还可以通过在JavaConfig类上使用特定于存储的@ Enable $ {store}存储库注释来触发存储库基础结构。有关Spring容器的基于Java的配置的介绍，请参阅Spring参考文档中的JavaConfig。

启用S​​pring Data存储库的示例配置类似于以下内容：

Example 24. 基于样本注释的存储库配置

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

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

上面的示例使用JPA特定的注释，您可以根据实际使用的存储模块进行更改。这同样适用于EntityManagerFactory bean的定义。请参阅涵盖特定存储的配置的部分。

3.5.3. 独立使用

您还可以在Spring容器之外使用存储库基础结构 - 例如，在CDI环境中。您仍然需要在类路径中使用一些Spring库，但通常也可以通过编程方式设置存储库。提供存储库支持的Spring Data模块提供了一个特定于持久性技术的RepositoryFactory，您可以按如下方式使用它：

Example 25. 存储库工厂的独立使用

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

3.6. Spring Data 存储库的自定义实现

本节介绍存储库自定义以及片段如何构成复合存储库。

当查询方法需要不同的行为或无法通过查询派生实现时，则需要提供自定义实现。Spring Data存储库允许您提供自定义存储库代码，并将其与通用CRUD抽象和查询方法功能集成。

3.6.1. 自定义单个存储库

要使用自定义功能丰富存储库，必须首先定义片段接口和自定义功能的实现，如以下示例所示：

Example 26. 自定义存储库功能的接口

interface CustomizedUserRepository {
  void someCustomMethod(User user);
}

然后，您可以让您的存储库接口从片段接口进一步扩展，如以下示例所示：

Example 27. 自定义存储库功能的实现

class CustomizedUserRepositoryImpl implements CustomizedUserRepository {

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

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

实现本身不依赖于Spring Data，可以是常规的Spring bean。因此，您可以使用标准依赖项注入行为来注入对其他bean（例如JdbcTemplate）的引用，参与方面等。

您可以让存储库接口扩展片段接口，如以下示例所示：示例28.

Example 28. 对存储库界面的更改

interface UserRepository extends CrudRepository, CustomizedUserRepository {

  // Declare query methods here
}

使用存储库接口扩展片段接口可以组合CRUD和自定义功能，并使其可供客户端使用。

Spring Data存储库通过使用形成存储库组合的片段来实现。片段是基本存储库，功能方面（如QueryDsl），自定义接口及其实现。每次向存储库界面添加接口时，都可以通过添加片段来增强组合。每个Spring Data模块都提供了基本存储库和存储库方面的实现。

以下示例显示了自定义接口及其实现：示例29.

Example 29. 具有其实现的片段

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的自定义存储库的接口：

Example 30. 对存储库界面的更改

interface UserRepository extends CrudRepository, HumanRepository, ContactRepository {

  // Declare query methods here
}

存储库可以由多个自定义实现组成，这些实现按其声明的顺序导入。自定义实现的优先级高于基本实现和存储库方面。如果两个片段提供相同的方法签名，则此排序允许您覆盖基本存储库和方面方法并解决歧义。存储库片段不限于在单个存储库接口中使用。多个存储库可以使用片段接口，允许您跨不同的存储库重用自定义。

以下示例显示了存储库片段及其实现：

Example 31. 碎片压倒一切 save(…)

interface CustomizedSave {
   S save(S entity);
}

class CustomizedSaveImpl implements CustomizedSave {

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

以下示例显示了使用前面的存储库片段的存储库：

Example 32. 自定义存储库接口

interface UserRepository extends CrudRepository, CustomizedSave {
}

interface PersonRepository extends CrudRepository, CustomizedSave {
}

配置

如果使用命名空间配置，则存储库基础结构会尝试通过扫描其找到存储库的包下面的类来自动检测自定义实现片段。这些类需要遵循将命名空间元素的repository-impl-postfix属性附加到片段接口名称的命名约定。此后缀默认为Impl。以下示例显示了使用默认后缀的存储库以及为后缀设置自定义值的存储库：

Example 33. 配置示例

前面示例中的第一个配置尝试查找名为com.acme.repository.CustomizedUserRepositoryImpl的类，以充当自定义存储库实现。第二个示例尝试查找com.acme.repository.CustomizedUserRepositoryMyPostfix。

解决歧义

如果在不同的包中找到具有匹配类名的多个实现，则Spring Data使用bean名称来标识要使用的名称。

给定前面显示的CustomizedUserRepository的以下两个自定义实现，使用第一个实现。它的bean名称是customizedUserRepositoryImpl，它与片段接口（CustomizedUserRepository）和后缀Impl的名称相匹配。

Example 34. 无差别实现的解决方案

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
}

如果使用@Component（“specialCustom”）注释UserRepository接口，则bean名称加上Impl将匹配为com.acme.impl.two中的存储库实现定义的名称，并使用它而不是第一个。

手动接线

如果您的自定义实现仅使用基于注释的配置和自动装配，则前面显示的方法效果很好，因为它被视为任何其他Spring bean。如果您的实现片段bean需要特殊连接，您可以声明bean并根据前一节中描述的约定命名它。然后，基础结构按名称引用手动定义的bean定义，而不是自己创建一个。以下示例显示如何手动连接自定义实现：

Example 35. 自定义实现的手动连接

3.6.2. 自定义Base Repository

当您要自定义基本存储库行为以便所有存储库都受到影响时，上一节中描述的方法需要自定义每个存储库接口。要改为更改所有存储库的行为，可以创建一个扩展特定于持久性技术的存储库基类的实现。然后，此类充当存储库代理的自定义基类，如以下示例所示：

Example 36. 自定义存储库基类

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
  }
}

该类需要具有特定于存储的存储库工厂实现所使用的超类的构造函数。如果存储库基类具有多个构造函数，则覆盖采用EntityInformation和特定于存储的基础结构对象（例如EntityManager或模板类）的构造函数。

最后一步是使Spring Data Infrastructure了解自定义存储库基类。在Java配置中，您可以使用@ Enable $ {store}存储库注释的repositoryBaseClass属性来执行此操作，如以下示例所示：

Example 37. 使用JavaConfig配置自定义存储库基类

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

XML命名空间中提供了相应的属性，如以下示例所示：

Example 38. 使用XML配置自定义存储库基类

3.7. 从聚合根发布事件

由存储库管理的实体是聚合根。在域驱动设计应用程序中，这些聚合根通常会发布域事件。Spring Data提供了一个名为@DomainEvents的注释，您可以在聚合根的方法上使用该注释，以使该发布尽可能简单，如以下示例所示：

Example 39. 从聚合根公开事件域事件

class AnAggregateRoot {

    @DomainEvents 
    Collection