yongboyhood

Spring Data JPA 中文文档 markdown 版

# Spring Data Jpa 文档

标签（空格分隔）： JPA Spring

---

Spring Data JPA - 参考文档
======================

Oliver
Gierke Thomas Darimont
Christoph Strobl
Mark Paluch
杰伊布莱恩特
版本 2.1.0.M3,2018-05-17

©2008-2018原作者。

本文件副本可供您自行使用并分发给其他人，前提是您不收取任何此类副本的费用，并进一步规定每份副本均包含此版权声明，无论是以印刷版还是电子版分发。

目录

*   [前言](#preface)
    *   [1.项目元数据](#project)
    *   [2.新的＆值得注意的](#new-features)
        *   [2.1。Spring Data JPA 1.11中的新特性](#new-features.1-11-0)
        *   [2.2。Spring Data JPA 1.10中的新特性](#new-features.1-10-0)
    *   [3.依赖性](#dependencies)
        *   [3.1。Spring Boot的依赖管理](#dependencies.spring-boot)
        *   [3.2。Spring框架](#dependencies.spring-framework)
    *   [4.使用Spring数据存储库](#repositories)
        *   [4.1。核心概念](#repositories.core-concepts)
        *   [4.2。查询方法](#repositories.query-methods)
        *   [4.3。定义存储库接口](#repositories.definition)
            *   [4.3.1。微调储存库定义](#repositories.definition-tuning)
            *   [4.3.2。仓库方法的空处理](#repositories.nullability)
            *   [4.3.3。将存储库与多个Spring数据模块一起使用](#repositories.multiple-modules)
        *   [4.4。定义查询方法](#repositories.query-methods.details)
            *   [4.4.1。查询查询策略](#repositories.query-methods.query-lookup-strategies)
            *   [4.4.2。查询创建](#repositories.query-methods.query-creation)
            *   [4.4.3。属性表达式](#repositories.query-methods.query-property-expressions)
            *   [4.4.4。特殊参数处理](#repositories.special-parameters)
            *   [4.4.5。限制查询结果](#repositories.limit-query-result)
            *   [4.4.6。流式查询结果](#repositories.query-streaming)
            *   [4.4.7。异步查询结果](#repositories.query-async)
        *   [4.5。创建存储库实例](#repositories.create-instances)
            *   [4.5.1。XML配置](#repositories.create-instances.spring)
            *   [4.5.2。JavaConfig](#repositories.create-instances.java-config)
            *   [4.5.3。独立使用](#repositories.create-instances.standalone)
        *   [4.6。Spring数据仓库的自定义实现](#repositories.custom-implementations)
            *   [4.6.1。定制个人存储库](#repositories.single-repository-behavior)
            *   [4.6.2。自定义基础知识库](#repositories.customize-base-repository)
        *   [4.7。从聚合根发布事件](#core.domain-events)
        *   [4.8。Spring数据扩展](#core.extensions)
            *   [4.8.1。Querydsl扩展](#core.extensions.querydsl)
            *   [4.8.2。Web支持](#core.web)
            *   [4.8.3。存储库Poppop](#core.repository-populators)
*   [参考文档](#reference)
    *   [5\. JPA存储库](#jpa.repositories)
        *   [5.1。介绍](#jpa.introduction)
            *   [5.1.1。Spring命名空间](#jpa.namespace)
            *   [5.1.2。基于注释的配置](#jpa.java-config)
        *   [5.2。坚持实体](#jpa.entity-persistence)
            *   [5.2.1。保存实体](#jpa.entity-persistence.saving-entites)
        *   [5.3。查询方法](#jpa.query-methods)
            *   [5.3.1。查询查询策略](#jpa.sample-app.finders.strategies)
            *   [5.3.2。查询创建](#jpa.query-methods.query-creation)
            *   [5.3.3。使用JPA命名查询](#jpa.query-methods.named-queries)
            *   [5.3.4。运用`@Query`](#jpa.query-methods.at-query)
            *   [5.3.5。使用排序](#jpa.query-methods.sorting)
            *   [5.3.6。使用命名参数](#jpa.named-parameters)
            *   [5.3.7。使用SpEL表达式](#jpa.query.spel-expressions)
            *   [5.3.8。修改查询](#jpa.modifying-queries)
            *   [5.3.9。应用查询提示](#jpa.query-hints)
            *   [5.3.10。配置提取和LoadGraphs](#jpa.entity-graph)
            *   [5.3.11。预测](#projections)
        *   [5.4。存储过程](#jpa.stored-procedures)
        *   [5.5。产品规格](#specifications)
        *   [5.6。按实例查询](#query-by-example)
            *   [5.6.1。介绍](#query-by-example.introduction)
            *   [5.6.2。用法](#query-by-example.usage)
            *   [5.6.3。示例匹配器](#query-by-example.matchers)
            *   [5.6.4。执行一个例子](#query-by-example.execution)
        *   [5.7。事务性](#transactions)
            *   [5.7.1。事务查询方法](#transactional-query-methods)
        *   [5.8。锁定](#locking)
        *   [5.9。审计](#auditing)
            *   [5.9.1。基本](#auditing.basics)
            *   [5.9.2。JPA审计](#jpa.auditing)
        *   [5.10。其他注意事项](#jpa.misc)
            *   [5.10.1。使用`JpaContext`在自定义实现](#jpa.misc.jpa-context)
            *   [5.10.2。合并持久性单元](#jpa.misc.merging-persistence-units)
            *   [5.10.3。CDI集成](#jpd.misc.cdi-integration)
*   [附录](#appendix)
    *   [附录A：命名空间参考](#repositories.namespace-reference)
        *   [该``元素](#populator.namespace-dao-config)
    *   [附录B：Poppers命名空间参考](#populator.namespace-reference)
        *   [元素](#namespace-dao-config)
    *   [附录C：存储库查询关键字](#repository-query-keywords)
        *   [支持的查询关键字](#_supported_query_keywords)
    *   [附录D：存储库查询返回类型](#repository-query-return-types)
        *   [支持的查询返回类型](#_supported_query_return_types)
    *   [附录E：常见问题](#faq)
        *   [共同](#_common)
        *   [基础设施](#_infrastructure)
        *   [审计](#_auditing)
    *   [附录F：术语表](#glossary)

[](#preface)前言
==============

Spring Data JPA为Java持久性API（JPA）提供存储库支持。它简化了需要访问JPA数据源的应用程序的开发。

[](#project)1.项目元数据
-------------------

*   版本控制 \- [http://github.com/spring-projects/spring-data-jpa](https://github.com/spring-projects/spring-data-jpa)

*   Bugtracker - [https://jira.spring.io/browse/DATAJPA](https://jira.spring.io/browse/DATAJPA)

*   发行版本库 \- [https://repo.spring.io/libs-release](https://repo.spring.io/libs-release)

*   里程碑存储库 \- [https://repo.spring.io/libs-milestone](https://repo.spring.io/libs-milestone)

*   快照存储库 \- [https://repo.spring.io/libs-snapshot](https://repo.spring.io/libs-snapshot)


[](#new-features)2.新的＆值得注意的
---------------------------

### [](#new-features.1-11-0)2.1。Spring Data JPA 1.11中的新特性

Spring Data JPA 1.11增加了以下功能：

*   改进与Hibernate 5.2的兼容性。

*   [通过示例](#query-by-example)支持任意匹配模式。

*   分页查询执行优化。

*   支持`exists`存储库查询派生中的投影。


### [](#new-features.1-10-0)2.2。Spring Data JPA 1.10中的新特性

Spring Data JPA 1.10增加了以下功能：

*   支持存储库查询方法中的[投影](#projections)。

*   [通过示例](#query-by-example)支持[查询](#query-by-example)。

*   以下注解已启用的基础上组成的注释：`@EntityGraph`，`@Lock`，`@Modifying`，`@Query`，`@QueryHints`，和`@Procedure`。

*   支持`Contains`集合表达式的关键字。

*   `AttributeConverter`为实现`ZoneId`JSR-310和ThreeTenBP的。

*   升级到Querydsl 4，Hibernate 5，OpenJPA 2.4和EclipseLink 2.6.1。


[](#dependencies)3.依赖性
----------------------

由于各个Spring Data模块的初始日期不同，它们中的大多数都带有不同的主版本号和次版本号。寻找兼容版本的最简单方法是依靠我们随定义的兼容版本提供的Spring Data Release BOM。在Maven项目中，您将在``POM 的部分声明这种依赖关系，如下所示：

示例1.使用Spring Data发行版BOM




          org.springframework.data
          spring-data-releasetrain
          ${release-train}
          import
          pom




目前的发行版本是`Lovelace-M3`。列车名称按字母顺序上升，目前可用的列车在[此处](https://github.com/spring-projects/spring-data-commons/wiki/Release-planning)列出。版本名称遵循以下模式：`${name}-${release}`，其中发布可以是下列之一：

*   `BUILD-SNAPSHOT`：当前快照

*   `M1`，`M2`等等：里程碑

*   `RC1`，`RC2`等等：发布候选人

*   `RELEASE`：GA版本

*   `SR1`，`SR2`等等：服务版本


在我们的[Spring Data示例存储库中](https://github.com/spring-projects/spring-data-examples/tree/master/bom)可以找到使用BOM的一个工作示例。有了这个，你可以在块中声明你想使用的Spring数据模块而不需要版本``，如下所示：

例2.声明一个依赖到Spring Data模块



        org.springframework.data
        spring-data-jpa



### [](#dependencies.spring-boot)3.1。Spring Boot的依赖管理

Spring Boot为您选择最新版本的Spring Data模块。如果您仍想升级到较新版本，请将该属性配置为您要使用`spring-data-releasetrain.version`的[火车名称和迭代](#dependencies.train-names)。

### [](#dependencies.spring-framework)3.2。Spring框架

当前版本的Spring Data模块需要版本5.0.6.RELEASE或更高版本的Spring Framework。这些模块也可能与该次要版本的旧版错误修复版本一起工作。但是，强烈建议使用该代中的最新版本。

[](#repositories)4.使用Spring数据存储库
--------------------------------

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

_Spring数据存储库文档和你的模块_

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

### [](#repositories.core-concepts)4.1。核心概念

Spring Data存储库抽象中的中心接口是`Repository`。它需要管理域类以及域类的ID类型作为类型参数。该接口主要作为标记接口来捕获要使用的类型，并帮助您发现扩展该接口的接口。该`CrudRepository`规定对于正在管理的实体类复杂的CRUD功能。

例3\. `CrudRepository`接口

    public interface CrudRepository
      extends Repository {

      S save(S entity);      (1)

      Optional findById(ID primaryKey); (2)

      Iterable findAll();               (3)

      long count();                        (4)

      void delete(T entity);               (5)

      boolean existsById(ID primaryKey);   (6)

      // … more functionality omitted.
    }

**1**

保存给定的实体。

**2**

返回由给定ID标识的实体。

**3**

返回所有实体。

**4**

返回实体的数量。

**五**

删除给定的实体。

**6**

指示是否存在具有给定ID的实体。

我们还提供持久性技术特定抽象，如`JpaRepository`或`MongoRepository`。这些接口扩展`CrudRepository`并公开了持久化技术的基本功能，以及相当通用的持久化技术无关接口，例如`CrudRepository`。

除此之外`CrudRepository`，还有一个`PagingAndSortingRepository`抽象增加了其他方法来简化对实体的分页访问：

示例4\. `PagingAndSortingRepository`接口

    public interface PagingAndSortingRepository
      extends CrudRepository {

      Iterable findAll(Sort sort);

      Page findAll(Pageable pageable);
    }

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

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

除了查询方法外，count和delete查询的查询派生都是可用的。以下列表显示派生计数查询的接口定义：

示例5.派生计数查询

    interface UserRepository extends CrudRepository {

      long countByLastname(String lastname);
    }

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

示例6.派生删除查询

    interface UserRepository extends CrudRepository {

      long deleteByLastname(String lastname);

      List removeByLastname(String lastname);
    }

### [](#repositories.query-methods)4.2。查询方法

标准CRUD功能存储库通常会在底层数据存储上进行查询。使用Spring Data，声明这些查询变成了一个四步过程：

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

        interface PersonRepository extends Repository { … }

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

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

3. 设置Spring以使用[JavaConfig](#repositories.create-instances.java-config)或[XML配置](#repositories.create-instances)为这些接口创建代理实例。

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

            import org.springframework.data.jpa.repository.config.EnableJpaRepositories;

            @EnableJpaRepositories
            class Config {}

    2. 要使用XML配置，请定义一个类似于以下的bean：


                           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:jpa="http://www.springframework.org/schema/data/jpa"
               xsi:schemaLocation="http://www.springframework.org/schema/beans
                 http://www.springframework.org/schema/beans/spring-beans.xsd
                 http://www.springframework.org/schema/data/jpa
                 http://www.springframework.org/schema/data/jpa/spring-jpa.xsd">






    这个例子中使用了JPA命名空间。如果您对任何其他商店使用存储库抽象，则需要将其更改为商店模块的相应名称空间声明。换句话说，你应该交换`jpa`赞成，例如`mongodb`。

    +另请注意，JavaConfig变体不会显式配置包，因为缺省情况下会使用注释类的包。要定制要扫描的软件包，请使用`basePackage…`特定于数据存储库的`@Enable${store}Repositories`注释的一个属性。

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

        class SomeClient {

          private final PersonRepository repository;

          SomeClient(PersonRepository repository) {
            this.repository = repository;
          }

          void doSomething() {
            List persons = repository.findByLastname("Matthews");
          }
        }


以下部分详细解释每一步：

*   [定义存储库接口](#repositories.definition)

*   [定义查询方法](#repositories.query-methods.details)

*   [创建存储库实例](#repositories.create-instances)

*   [Spring数据仓库的自定义实现](#repositories.custom-implementations)


### [](#repositories.definition)4.3。定义存储库接口

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

#### [](#repositories.definition-tuning)4.3.1。微调储存库定义

通常情况下，你的资料库接口扩展`Repository`，`CrudRepository`或`PagingAndSortingRepository`。或者，如果您不想扩展Spring Data接口，也可以使用注释库接口进行注释`@RepositoryDefinition`。扩展`CrudRepository`公开了一套完整的方法来操纵你的实体。如果您想选择暴露的方法，请将要公开的方法复制`CrudRepository`到您的域存储库中。

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

以下示例显示如何选择性地公开CRUD方法（`findById`以及`save`在这种情况下）：

示例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提供的数据（例如，如果使用JPA商店，该实现是`SimpleJpaRepository`），因为它们匹配中的方法签名`CrudRepository`。因此，`UserRepository`现在可以保存用户，通过ID查找单个用户，并触发查询以`Users`通过电子邮件地址查找。

中间存储库接口用注释`@NoRepositoryBean`。确保将该注释添加到Spring Data不应在运行时为其创建实例的所有存储库接口。

#### [](#repositories.nullability)4.3.2。仓库方法的空处理

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

*   `com.google.common.base.Optional`

*   `scala.Option`

*   `io.vavr.control.Option`

*   `javaslang.control.Option` （由于Javaslang已被弃用）


或者，查询方法可以选择不使用包装类型。然后通过返回来指示没有查询结果`null`。存储库方法返回集合，集合备选方案，包装器和流保证永远不会返回`null`，而是相应的空表示。有关详细信息，请参阅“ [存储库查询返回类型](#repository-query-return-types) ”。

##### [](#repositories.nullability.annotations)可空性注释

您可以使用[Spring Framework的可空性注释](https://docs.spring.io/spring/docs/5.0.6.RELEASE/spring-framework-reference/core.html#null-safety)来表示存储库方法的可空约束。它们提供了一个工具友好的方法，并`null`在运行期间进行选择性检查，如下所示：

*   [`@NonNullApi`](https://docs.spring.io/spring/docs/5.0.6.RELEASE/javadoc-api/org/springframework/lang/NonNullApi.html)：在包级别上用于声明参数和返回值的默认行为是不接受或生成`null`值。

*   [`@NonNull`](https://docs.spring.io/spring/docs/5.0.6.RELEASE/javadoc-api/org/springframework/lang/NonNull.html)：用于参数或返回值，不能是`null` （参数不需要，返回值`@NonNullApi`适用）。

*   [`@Nullable`](https://docs.spring.io/spring/docs/5.0.6.RELEASE/javadoc-api/org/springframework/lang/Nullable.html)：用于可以是的参数或返回值`null`。


Spring注释使用[JSR 305](https://jcp.org/en/jsr/detail?id=305)注释进行元注释（一种休眠但广泛传播的JSR）。JSR 305元注释让工具供应商（如[IDEA](https://www.jetbrains.com/help/idea/nullable-and-notnull-annotations.html)，[Eclipse](http://help.eclipse.org/oxygen/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/task-using_external_null_annotations.htm)和[Kotlin）](https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types)以通用方式提供空安全支持，而无需为Spring注释提供硬编码支持。要启用对查询方法的可空约束的运行时检查，您需要使用Spring的`@NonNullApi`in 激活包级别的非可空性`package-info.java`，如以下示例所示：

示例8.在中声明不可为空 `package-info.java`

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

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

以下示例显示了刚刚描述的许多技术：

例子9.使用不同的可空性约束

    package com.acme;                                                       (1)

    import org.springframework.lang.Nullable;

    interface UserRepository extends Repository {

      User getByEmailAddress(EmailAddress emailAddress);                    (2)

      @Nullable
      User findByEmailAddress(@Nullable EmailAddress emailAdress);          (3)

      Optional findOptionalByEmailAddress(EmailAddress emailAddress); (4)
    }

**1**

存储库驻留在我们为其定义非空行为的包（或子包）中。

**2**

`EmptyResultDataAccessException`当执行的查询不产生结果时抛出一个。`IllegalArgumentException`当`emailAddress`交给方法时抛出一个`null`。

**3**

`null`当执行的查询不会产生结果时返回。也接受`null`作为的价值`emailAddress`。

**4**

`Optional.empty()`当执行的查询不会产生结果时返回。`IllegalArgumentException`当`emailAddress`交给方法时抛出一个`null`。

##### [](#repositories.nullability.kotlin)基于Kotlin的知识库中的可空性

Kotlin定义了可用于语言的可[空性约束](https://kotlinlang.org/docs/reference/null-safety.html)。Kotlin代码编译为字节码，该字节码不通过方法签名表示可空约束，而是通过编译后的元数据表示。确保`kotlin-reflect`在项目中包含JAR，以便对Kotlin的可空性限制进行反省。Spring Data存储库使用语言机制来定义这些约束以应用相同的运行时检查，如下所示：

例10.在Kotlin存储库上使用可空性约束

    interface UserRepository : Repository {

      fun findByUsername(username: String): User     (1)

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

**1**

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

**2**

该方法接受`null`的`firstname`参数，并返回`null`，如果查询执行不产生结果。

#### [](#repositories.multiple-modules)4.3.3。将存储库与多个Spring数据模块一起使用

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

1. 如果存储库定义[扩展了特定于模块的存储库](#repositories.multiple-modules.types)，那么它是特定Spring Data模块的有效候选者。

2. 如果域类[使用特定于模块的类型注释进行注释](#repositories.multiple-modules.annotations)，则它是特定的Spring Data模块的有效候选者。Spring Data模块接受第三方注释（比如JPA `@Entity`）或者提供他们自己的注解（例如`@Document`Spring Data MongoDB和Spring Data Elasticsearch）。


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

示例11.使用模块特定接口的存储库定义

    interface MyRepository extends JpaRepository { }

    @NoRepositoryBean
    interface MyBaseRepository extends JpaRepository {
      …
    }

    interface UserRepository extends MyBaseRepository {
      …
    }

`MyRepository`并在其类型层次中进行`UserRepository`扩展`JpaRepository`。它们是Spring Data JPA模块的有效候选者。

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

示例12.使用通用接口的存储库定义

    interface AmbiguousRepository extends Repository {
     …
    }

    @NoRepositoryBean
    interface MyBaseRepository extends CrudRepository {
      …
    }

    interface AmbiguousUserRepository extends MyBaseRepository {
      …
    }

`AmbiguousRepository`和`AmbiguousUserRepository`仅延伸`Repository`，并`CrudRepository`在他们的类型层次。虽然在使用独特的Spring Data模块时这非常好，但多个模块无法区分这些存储库应绑定到哪个特定的Spring Data。

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

示例13.使用带注释的域类的存储库定义

    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`注解注释的。

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

示例14.使用具有混合注释的域类的存储库定义

    interface JpaPersonRepository extends Repository {
     …
    }

    interface MongoDBPersonRepository extends Repository {
     …
    }

    @Entity
    @Document
    class Person {
      …
    }

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

[存储库类型细节](#repositories.multiple-modules.types)和[区分域类注释](#repositories.multiple-modules.annotations)用于严格的存储库配置，以识别特定的Spring Data模块的存储库候选项。可以在相同的域类型上使用多个持久性技术特定的注释，并且允许跨多个持久性技术重用域类型。但是，Spring Data不再可以确定绑定存储库的唯一模块。

区分存储库的最后一种方法是通过确定存储库基础包的范围。基本软件包定义了扫描存储库接口定义的起点，这意味着存储库定义位于相应的软件包中。默认情况下，注释驱动的配置使用配置类的包。[基于XML的配置中](#repositories.create-instances.spring)的[基础包](#repositories.create-instances.spring)是强制性的。

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

示例15.基础包的注释驱动配置

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

### [](#repositories.query-methods.details)4.4。定义查询方法

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

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

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


可用选项取决于实际商店。但是，必须有一个策略来决定创建什么实际查询。下一节介绍可用的选项。

#### [](#repositories.query-methods.query-lookup-strategies)4.4.1。查询查询策略

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

*   `CREATE`尝试从查询方法名称构造特定于商店的查询。一般的方法是从方法名称中移除一组已知的前缀，并解析该方法的其余部分。您可以在“ [查询创建](#repositories.query-methods.query-creation) ”中阅读有关查询构建的更多信息。

*   `USE_DECLARED_QUERY`尝试查找已声明的查询，并在找不到某个查询时引发异常。查询可以通过某处的注释或其他方式声明。查阅特定商店的文档以查找该商店的可用选项。如果存储库基础结构在引导时未找到该方法的已声明查询，则会失败。

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


#### [](#repositories.query-methods.query-creation)4.4.2。查询创建

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

示例16.从方法名称创建查询

    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`）来应用静态排序。要创建支持动态排序的查询方法，请参阅“ [特殊参数处理](#repositories.special-parameters) ”。


#### [](#repositories.query-methods.query-property-expressions)4.4.3。属性表达式

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

    List findByAddressZipCode(ZipCode zipCode);

假设a `Person`有一个`Address`with `ZipCode`。在这种情况下，该方法创建属性遍历`x.address.zipCode`。解析算法首先将整个part（`AddressZipCode`）作为属性进行解释，然后检查该域名是否具有该名称（未添加大小）。如果算法成功，则使用该属性。如果不是的话，该算法将来自右侧的骆驼案件部分的来源拆分为头部和尾部，并尝试找到相应的属性 \- 在我们的示例中`AddressZip`和`Code`。如果算法找到具有该头部的属性，它将采用尾部并从该处继续构建树，然后按照刚刚描述的方式分割尾部。如果第一次分割不匹配，则算法将分割点移到左侧（`Address`，`ZipCode`）并继续。

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

为了解决这个歧义，你可以`\_`在你的方法名称中使用手动定义遍历点。所以我们的方法名称如下所示：

    List findByAddress_ZipCode(ZipCode zipCode);

因为我们将下划线字符视为保留字符，所以我们强烈建议遵循以下标准Java命名约定（即，不使用属性名称中的下划线，而是使用驼峰大小写代替）。

#### [](#repositories.special-parameters)4.4.4。特殊参数处理

要处理查询中的参数，请定义方法参数，如前面的示例中所示。除此之外，基础设施承认某些特定的类型，如`Pageable`和`Sort`，动态地应用分页和排序，以查询。以下示例演示了这些功能：

例子17\. 在查询方法中使用`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`实例传递给查询方法，以动态地将分页添加到静态定义的查询中。A `Page`知道可用元素和页面的总数。它通过基础设施触发计数查询来计算总数。由于这可能很昂贵（取决于所使用的商店），您可以返回一个`Slice`。A `Slice`只知道下一个`Slice`是否可用，这在走过更大的结果集时可能足够了。

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

要找出您为整个查询获得的页数，您必须触发额外的计数查询。默认情况下，此查询来自您实际触发的查询。

#### [](#repositories.limit-query-result)4.4.5。限制查询结果

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

示例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`关键字中。

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

通过使用`Sort`参数限制结果与动态排序结合使用，可以表达“K”最小以及“K”最大元素的查询方法。

#### [](#repositories.query-streaming)4.4.6。流式查询结果

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

示例19.使用Java 8对查询的结果进行流式处理 `Stream`

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

    Stream readAllByFirstnameNotNull();

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

甲`Stream`潜在包装底层数据存储专用资源，因此必须在使用之后被关闭。您可以`Stream`通过使用该`close()`方法或使用Java 7 `try-with-resources`块手动关闭，如以下示例所示：

示例20.使用`Stream`try-with-resources块中的结果

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

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

#### [](#repositories.query-async)4.4.7。异步查询结果

通过使用[Spring的异步方法执行功能，](https://docs.spring.io/spring/docs/5.0.6.RELEASE/spring-framework-reference/integration.html#scheduling)可以异步运行存储库查询。这意味着该方法在调用时立即返回，而实际查询执行发生在已提交给Spring的任务中`TaskExecutor`。异步查询执行与反应式查询执行不同，不应混用。有关被动支持的更多详细信息，请参阅商店专用文档。以下示例显示了一些异步查询：

    @Async
    Future findByFirstname(String firstname);               (1)

    @Async
    CompletableFuture findOneByFirstname(String firstname); (2)

    @Async
    ListenableFuture findOneByLastname(String lastname);    (3)

**1**

使用`java.util.concurrent.Future`作为返回类型。

**2**

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

**3**

使用a `org.springframework.util.concurrent.ListenableFuture`作为返回类型。

### [](#repositories.create-instances)4.5。创建存储库实例

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

#### [](#repositories.create-instances.spring)4.5.1。XML配置

每个Spring Data模块都包含一个`repositories`元素，可让您定义Spring为您扫描的基本包，如以下示例所示：

示例21.通过XML启用Spring Data存储库


          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns="http://www.springframework.org/schema/data/jpa"
      xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/data/jpa
        http://www.springframework.org/schema/data/jpa/spring-jpa.xsd">





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

##### [](#_using_filters)使用过滤器

默认情况下，基础架构将拾取扩展`Repository`位于已配置基础包下的持久性技术特定子接口的每个接口，并为其创建一个bean实例。但是，您可能需要更细致地控制哪些接口具有为其创建的bean实例。要做到这一点，使用``和``内部元素``的元素。语义与Spring的上下文命名空间中的元素完全等价。有关详细信息，请参阅这些元素的[Spring参考文档](https://docs.spring.io/spring/docs/5.0.6.RELEASE/spring-framework-reference/core.html#beans-scanning-filters)。

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

例22.使用排除过滤器元素





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

#### [](#repositories.create-instances.java-config)4.5.2。JavaConfig

存储库基础结构也可以通过`@Enable${store}Repositories`在JavaConfig类上使用特定于商店的注释来触发。有关Spring容器的基于Java的配置的介绍，请参阅[Spring参考文档中的JavaConfig](https://docs.spring.io/spring/docs/5.0.6.RELEASE/spring-framework-reference/core.html#beans-java)。

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

示例23.基于示例注释的存储库配置

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

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

前面的示例使用JPA特定的注释，它将根据您实际使用的商店模块进行更改。这同样适用于`EntityManagerFactory`bean 的定义。请参阅包含特定于商店的配置的章节。

#### [](#repositories.create-instances.standalone)4.5.3。独立使用

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

示例24.存储库工厂的独立使用

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

### [](#repositories.custom-implementations)4.6。Spring数据仓库的自定义实现

本节涵盖存储库自定义以及片段如何形成组合存储库。

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

#### [](#repositories.single-repository-behavior)4.6.1。定制个人存储库

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

示例25.自定义存储库功能的接口

    interface CustomizedUserRepository {
      void someCustomMethod(User user);
    }

然后，您可以让您的存储库接口另外从分段接口扩展，如以下示例所示：

示例26.实现定制存储库功能

    class CustomizedUserRepositoryImpl implements CustomizedUserRepository {

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

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

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

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

示例27.对存储库接口的更改

    interface UserRepository extends CrudRepository, CustomizedUserRepository {

      // Declare query methods here
    }

使用存储库接口扩展分段接口将CRUD和自定义功能结合起来，并将其提供给客户端。

Spring数据存储库通过使用构成存储库组合的片段来实现。片段是基础知识库，功能方面（如[QueryDsl](#core.extensions.querydsl)）以及自定义接口及其实现。每次将接口添加到存储库接口时，都会通过添加片段来增强组合。每个Spring Data模块提供基础知识库和存储库方面实现。

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

示例28.碎片及其实现

    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`：

示例29.您的存储库接口的更改

    interface UserRepository extends CrudRepository, HumanRepository, ContactRepository {

      // Declare query methods here
    }

存储库可能由多个自定义实现组成，这些自定义实现按其声明的顺序导入。自定义实现具有比基本实现和存储库方面更高的优先级。这种排序使您可以覆盖基本存储库和方面方法，并在两个片段提供相同的方法签名时解决歧义。存储库片段不限于在单个存储库接口中使用。多个存储库可能会使用片段接口，让您可以在不同存储库之间重复使用自定义设置。

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

例子30.片段覆盖 `save(…)`

    interface CustomizedSave {
      S save(S entity);
    }

    class CustomizedSaveImpl implements CustomizedSave {

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

以下示例显示使用上述存储库片段的存储库：

示例31.定制的存储库接口

    interface UserRepository extends CrudRepository, CustomizedSave {
    }

    interface PersonRepository extends CrudRepository, CustomizedSave {
    }

##### [](#_configuration)组态

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

示例32.配置示例





上例中的第一个配置尝试查找调用的类`com.acme.repository.CustomizedUserRepositoryImpl`以充当自定义存储库实现。第二个例子试图查找`com.acme.repository.CustomizedUserRepositoryMyPostfix`。

###### [](#repositories.single-repository-behaviour.ambiguity)解决歧义

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

鉴于`CustomizedUserRepository`前面所示的以下两个自定义实现，将使用第一个实现。它的bean名称是`customizedUserRepositoryImpl`，它匹配fragment接口（`CustomizedUserRepository`）加上后缀`Impl`。

例子33.解析实现

    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
    }

如果使用注释`UserRepository`接口`@Component("specialCustom")`，那么bean名称加上，`Impl`然后与为存储库实现定义的名称相匹配`com.acme.impl.two`，并使用它来代替第一个。

###### [](#repositories.manual-wiring)手动接线

如果您的自定义实现仅使用基于注释的配置和自动装配，则上述方法显示效果良好，因为它被视为任何其他Spring bean。如果你的实现片段bean需要特殊的布线，你可以声明这个bean并根据[前面的章节中](#repositories.single-repository-behaviour.ambiguity)描述的约定来命名它。基础架构然后通过名称引用手动定义的bean定义，而不是自己创建一个。以下示例显示如何手动连接自定义实现：

例34.自定义实现的手动连线







#### [](#repositories.customize-base-repository)4.6.2。自定义基础知识库

上[一节中](#repositories.manual-wiring)描述的方法需要在定制基本存储库行为时定制每个存储库接口，以便所有存储库都受到影响。为了改变所有存储库的行为，可以创建一个扩展持久性技术特定存储库基类的实现。然后，该类将作为存储库代理的自定义基类，如以下示例所示：

示例35.定制存储库基类

    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基础设施知道定制的存储库基类。在Java配置中，您可以使用注释的`repositoryBaseClass`属性来完成此操作`@Enable${store}Repositories`，如以下示例所示：

示例36.使用JavaConfig配置定制存储库基类

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

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

示例37.使用XML配置定制存储库基类

             base-class="….MyRepositoryImpl" />

### [](#core.domain-events)4.7。从聚合根发布事件

由存储库管理的实体是聚合根。在Domain-Driven Design应用程序中，这些聚合根通常会发布域事件。Spring Data提供了一个注释，称为`@DomainEvents`可用于聚合根方法的注释，以使该出版物尽可能地简单，如以下示例所示：

例子38.从聚合根暴露域事件

    class AnAggregateRoot {

        @DomainEvents (1)
        Collection

Spring Data JPA 中文文档 markdown 版

你可能感兴趣的:(JPA)