JPA

Spring JPA（位于 org.springframework.orm.jpa 包下）为 Java 持久性 API 提供了全面的支持，其方式类似于与 Hibernate 的集成，同时了解底层实现以提供额外的功能。

在 Spring 环境中设置 JPA 的三种方法

Spring JPA 支持提供了三种设置 JPA EntityManagerFactory 的方法，应用程序使用该方法获取实体管理器。

使用 LocalEntityManagerFactoryBean

您只能在简单的部署环境（例如独立应用程序和集成测试）中使用此选项。

LocalEntityManagerFactoryBean 创建一个适合简单部署环境的 EntityManagerFactory，在这些环境中，应用程序仅使用 JPA 进行数据访问。工厂 Bean 使用 JPA 的 PersistenceProvider 自动检测机制（根据 JPA 的 Java SE 引导），并且在大多数情况下，只需要指定持久化单元名称。以下 XML 示例配置了这样的 Bean

<beans>
	<bean id="myEmf" class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean">
		<property name="persistenceUnitName" value="myPersistenceUnit"/>
	</bean>
</beans>

这种形式的 JPA 部署是最简单也是最有限的。您无法引用现有的 JDBC DataSource Bean 定义，并且不支持全局事务。此外，持久化类的编织（字节码转换）是特定于提供者的，通常需要在启动时指定特定的 JVM 代理。此选项仅适用于独立应用程序和测试环境，JPA 规范为此而设计。

从 JNDI 获取 EntityManagerFactory

在部署到 Jakarta EE 服务器时可以使用此选项。查看服务器的文档，了解如何将自定义 JPA 提供者部署到服务器，从而允许使用与服务器默认提供者不同的提供者。

从 JNDI 获取 EntityManagerFactory（例如在 Jakarta EE 环境中）只是更改 XML 配置的问题，如下面的示例所示

<beans>
	<jee:jndi-lookup id="myEmf" jndi-name="persistence/myPersistenceUnit"/>
</beans>

此操作假设标准 Jakarta EE 引导。Jakarta EE 服务器会自动检测持久化单元（实际上是应用程序 jar 中的 META-INF/persistence.xml 文件）和 Jakarta EE 部署描述符（例如 web.xml）中的 persistence-unit-ref 条目，并为这些持久化单元定义环境命名上下文位置。

在这种情况下，整个持久化单元部署，包括持久化类的编织（字节码转换），都由 Jakarta EE 服务器负责。JDBC DataSource 通过 META-INF/persistence.xml 文件中的 JNDI 位置定义。EntityManager 事务与服务器的 JTA 子系统集成。Spring 只是使用获得的 EntityManagerFactory，通过依赖注入将其传递给应用程序对象，并管理持久化单元的事务（通常通过 JtaTransactionManager）。

如果您在同一个应用程序中使用多个持久化单元，则这些通过 JNDI 获取的持久化单元的 Bean 名称应与应用程序用来引用它们的持久化单元名称匹配（例如，在 @PersistenceUnit 和 @PersistenceContext 注解中）。

使用 LocalContainerEntityManagerFactoryBean

您可以在基于 Spring 的应用程序环境中使用此选项来实现完整的 JPA 功能。这包括 Tomcat 等 Web 容器、独立应用程序以及具有复杂持久化需求的集成测试。

LocalContainerEntityManagerFactoryBean 提供了对 EntityManagerFactory 配置的完全控制，适用于需要细粒度自定义的环境。LocalContainerEntityManagerFactoryBean 基于 persistence.xml 文件、提供的 dataSourceLookup 策略和指定的 loadTimeWeaver 创建 PersistenceUnitInfo 实例。因此，可以使用 JNDI 之外的自定义数据源，并控制编织过程。以下示例展示了 LocalContainerEntityManagerFactoryBean 的典型 Bean 定义。

<beans>
	<bean id="myEmf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
		<property name="dataSource" ref="someDataSource"/>
		<property name="loadTimeWeaver">
			<bean class="org.springframework.instrument.classloading.InstrumentationLoadTimeWeaver"/>
		</property>
	</bean>
</beans>

以下示例展示了一个典型的 persistence.xml 文件

<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
	<persistence-unit name="myUnit" transaction-type="RESOURCE_LOCAL">
		<mapping-file>META-INF/orm.xml</mapping-file>
		<exclude-unlisted-classes/>
	</persistence-unit>
</persistence>
<exclude-unlisted-classes/> 快捷方式表示不应扫描带注解的实体类。显式 'true' 值（<exclude-unlisted-classes>true</exclude-unlisted-classes/>）也表示不扫描。<exclude-unlisted-classes>false</exclude-unlisted-classes/> 会触发扫描。但是，如果希望进行实体类扫描，建议省略 exclude-unlisted-classes 元素。

使用 LocalContainerEntityManagerFactoryBean 是功能最强大的 JPA 设置选项，允许在应用程序中进行灵活的本地配置。它支持链接到现有的 JDBC DataSource，支持本地和全局事务等等。但是，它也对运行时环境提出了要求，例如，如果持久化提供程序需要字节码转换，则需要一个支持编织的类加载器。

此选项可能会与 Jakarta EE 服务器的内置 JPA 功能冲突。在完整的 Jakarta EE 环境中，请考虑从 JNDI 获取您的 EntityManagerFactory。或者，在您的 LocalContainerEntityManagerFactoryBean 定义中指定一个自定义 persistenceXmlLocation（例如，META-INF/my-persistence.xml），并在您的应用程序 jar 文件中只包含一个具有该名称的描述符。由于 Jakarta EE 服务器只查找默认的 META-INF/persistence.xml 文件，因此它会忽略此类自定义持久化单元，从而避免与 Spring 驱动的 JPA 设置发生冲突。（例如，这适用于 Resin 3.1。）

何时需要加载时编织？

并非所有 JPA 提供者都需要 JVM 代理。Hibernate 就是一个不需要代理的例子。如果您的提供者不需要代理，或者您有其他替代方案，例如通过自定义编译器或 Ant 任务在构建时应用增强，则不应使用加载时编织器。

LoadTimeWeaver 接口是 Spring 提供的一个类，它允许 JPA ClassTransformer 实例以特定方式插入，具体取决于环境是 Web 容器还是应用程序服务器。通过 代理 挂钩 ClassTransformers 通常效率不高。代理针对整个虚拟机工作，并检查加载的每个类，这在生产服务器环境中通常是不可取的。

Spring 为各种环境提供了一些 LoadTimeWeaver 实现，允许仅针对每个类加载器（而不是每个 VM）应用 ClassTransformer 实例。

有关 LoadTimeWeaver 实现及其设置的更多见解，请参阅 AOP 章节中的 Spring 配置，无论是通用的还是针对各种平台（如 Tomcat、JBoss 和 WebSphere）定制的。

如 Spring 配置 中所述，您可以使用 @EnableLoadTimeWeaving 注解或 context:load-time-weaver XML 元素配置一个上下文范围的 LoadTimeWeaver。所有 JPA LocalContainerEntityManagerFactoryBean 实例都会自动拾取这种全局编织器。以下示例展示了设置加载时编织器的首选方法，它提供平台的自动检测（例如 Tomcat 的可编织类加载器或 Spring 的 JVM 代理）以及编织器到所有支持编织的 Bean 的自动传播

<context:load-time-weaver/>

<bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
	...
</bean>

但是，如果需要，您可以通过 loadTimeWeaver 属性手动指定一个专用编织器，如下例所示

<bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
	<property name="loadTimeWeaver">
		<bean class="org.springframework.instrument.classloading.ReflectiveLoadTimeWeaver"/>
	</property>
</bean>

无论 LTW 如何配置，通过使用这种技术，依赖于检测的 JPA 应用程序可以在目标平台（例如 Tomcat）中运行，而无需代理。当托管应用程序依赖于不同的 JPA 实现时，这一点尤其重要，因为 JPA 变换器仅在类加载器级别应用，因此彼此隔离。

处理多个持久化单元

对于依赖于多个持久化单元位置（例如存储在类路径中的各种 JAR 中）的应用程序，Spring 提供了 PersistenceUnitManager 充当中央存储库，并避免持久化单元发现过程，这可能很昂贵。默认实现允许指定多个位置。这些位置被解析，然后通过持久化单元名称检索。（默认情况下，类路径将搜索 META-INF/persistence.xml 文件。）以下示例配置了多个位置

<bean id="pum" class="org.springframework.orm.jpa.persistenceunit.DefaultPersistenceUnitManager">
	<property name="persistenceXmlLocations">
		<list>
			<value>org/springframework/orm/jpa/domain/persistence-multi.xml</value>
			<value>classpath:/my/package/**/custom-persistence.xml</value>
			<value>classpath*:META-INF/persistence.xml</value>
		</list>
	</property>
	<property name="dataSources">
		<map>
			<entry key="localDataSource" value-ref="local-db"/>
			<entry key="remoteDataSource" value-ref="remote-db"/>
		</map>
	</property>
	<!-- if no datasource is specified, use this one -->
	<property name="defaultDataSource" ref="remoteDataSource"/>
</bean>

<bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
	<property name="persistenceUnitManager" ref="pum"/>
	<property name="persistenceUnitName" value="myCustomUnit"/>
</bean>

默认实现允许自定义 PersistenceUnitInfo 实例（在它们被馈送到 JPA 提供者之前），无论是声明式（通过其属性，影响所有托管单元）还是以编程方式（通过 PersistenceUnitPostProcessor，允许持久化单元选择）。如果没有指定 PersistenceUnitManager，则会创建一个并由 LocalContainerEntityManagerFactoryBean 在内部使用。

后台引导

LocalContainerEntityManagerFactoryBean 通过 bootstrapExecutor 属性支持后台启动，如下例所示

<bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
	<property name="bootstrapExecutor">
		<bean class="org.springframework.core.task.SimpleAsyncTaskExecutor"/>
	</property>
</bean>

实际的 JPA 提供程序启动将被移交给指定的执行器，然后并行运行到应用程序启动线程。公开的 EntityManagerFactory 代理可以注入到其他应用程序组件中，甚至能够响应 EntityManagerFactoryInfo 配置检查。但是，一旦其他组件访问实际的 JPA 提供程序（例如，调用 createEntityManager），这些调用将阻塞，直到后台启动完成。特别是，当您使用 Spring Data JPA 时，请确保也为其存储库设置延迟启动。

基于 JPA 实现 DAO：EntityManagerFactory 和 EntityManager

虽然 EntityManagerFactory 实例是线程安全的，但 EntityManager 实例不是。注入的 JPA EntityManager 的行为类似于从应用程序服务器的 JNDI 环境中获取的 EntityManager，如 JPA 规范所定义。它将所有调用委托给当前事务性 EntityManager（如果有）。否则，它将回退到每个操作创建一个新的 EntityManager，实际上使其使用线程安全。

可以通过使用注入的 EntityManagerFactory 或 EntityManager，在没有任何 Spring 依赖项的情况下编写针对普通 JPA 的代码。如果启用了 PersistenceAnnotationBeanPostProcessor，Spring 可以在字段和方法级别理解 @PersistenceUnit 和 @PersistenceContext 注释。以下示例显示了一个使用 @PersistenceUnit 注释的普通 JPA DAO 实现

  • Java

  • Kotlin

public class ProductDaoImpl implements ProductDao {

	private EntityManagerFactory emf;

	@PersistenceUnit
	public void setEntityManagerFactory(EntityManagerFactory emf) {
		this.emf = emf;
	}

	public Collection loadProductsByCategory(String category) {
		EntityManager em = this.emf.createEntityManager();
		try {
			Query query = em.createQuery("from Product as p where p.category = ?1");
			query.setParameter(1, category);
			return query.getResultList();
		}
		finally {
			if (em != null) {
				em.close();
			}
		}
	}
}
class ProductDaoImpl : ProductDao {

	private lateinit var emf: EntityManagerFactory

	@PersistenceUnit
	fun setEntityManagerFactory(emf: EntityManagerFactory) {
		this.emf = emf
	}

	fun loadProductsByCategory(category: String): Collection<*> {
		val em = this.emf.createEntityManager()
		val query = em.createQuery("from Product as p where p.category = ?1");
		query.setParameter(1, category);
		return query.resultList;
	}
}

前面的 DAO 不依赖于 Spring，并且仍然很好地适合 Spring 应用程序上下文。此外，DAO 利用注释来要求注入默认的 EntityManagerFactory，如下面的示例 bean 定义所示

<beans>

	<!-- bean post-processor for JPA annotations -->
	<bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor"/>

	<bean id="myProductDao" class="product.ProductDaoImpl"/>

</beans>

作为显式定义 PersistenceAnnotationBeanPostProcessor 的替代方案，请考虑在您的应用程序上下文配置中使用 Spring context:annotation-config XML 元素。这样做会自动注册所有用于基于注释的配置的 Spring 标准后处理器，包括 CommonAnnotationBeanPostProcessor 等。

请考虑以下示例

<beans>

	<!-- post-processors for all standard config annotations -->
	<context:annotation-config/>

	<bean id="myProductDao" class="product.ProductDaoImpl"/>

</beans>

这种 DAO 的主要问题是它总是通过工厂创建一个新的 EntityManager。您可以通过请求注入一个事务性 EntityManager（也称为“共享 EntityManager”，因为它是一个共享的、线程安全的实际事务性 EntityManager 的代理）来避免这种情况，而不是工厂。以下示例展示了如何做到这一点。

  • Java

  • Kotlin

public class ProductDaoImpl implements ProductDao {

	@PersistenceContext
	private EntityManager em;

	public Collection loadProductsByCategory(String category) {
		Query query = em.createQuery("from Product as p where p.category = :category");
		query.setParameter("category", category);
		return query.getResultList();
	}
}
class ProductDaoImpl : ProductDao {

	@PersistenceContext
	private lateinit var em: EntityManager

	fun loadProductsByCategory(category: String): Collection<*> {
		val query = em.createQuery("from Product as p where p.category = :category")
		query.setParameter("category", category)
		return query.resultList
	}
}

@PersistenceContext 注解有一个可选属性名为 type，它默认为 PersistenceContextType.TRANSACTION。您可以使用此默认值来接收一个共享的 EntityManager 代理。另一种选择，PersistenceContextType.EXTENDED，是一个完全不同的情况。这会导致一个所谓的扩展 EntityManager，它不是线程安全的，因此不能在并发访问的组件中使用，例如 Spring 管理的单例 bean。扩展 EntityManager 实例只应该在有状态的组件中使用，例如驻留在会话中的组件，EntityManager 的生命周期不与当前事务绑定，而是完全由应用程序决定。

方法级和字段级注入

您可以在类中的字段或方法上应用指示依赖注入的注解（例如 @PersistenceUnit 和 @PersistenceContext）——因此有了“方法级注入”和“字段级注入”这两个表达。字段级注解简洁易用，而方法级注解允许对注入的依赖项进行进一步处理。在这两种情况下，成员可见性（public、protected 或 private）都没有关系。

类级注解呢？

在 Jakarta EE 平台上，它们用于依赖声明，而不是资源注入。

注入的 EntityManager 是 Spring 管理的（知道正在进行的事务）。即使新的 DAO 实现使用 EntityManager 的方法级注入而不是 EntityManagerFactory，由于注解的使用，也不需要在 bean 定义中进行任何更改。

这种 DAO 风格的主要优势在于它只依赖于 Java 持久性 API。不需要导入任何 Spring 类。此外，由于 JPA 注解被理解，注入由 Spring 容器自动应用。从非侵入性的角度来看，这很有吸引力，并且对于 JPA 开发人员来说可能感觉更自然。

基于 @Autowired 实现 DAO（通常使用基于构造函数的注入）

@PersistenceUnit 和 @PersistenceContext 只能声明在方法和字段上。那么如何通过构造函数和其他 @Autowired 注入点提供 JPA 资源呢？

只要目标被定义为 bean（例如，通过 LocalContainerEntityManagerFactoryBean），EntityManagerFactory 可以轻松地通过构造函数和 @Autowired 字段/方法注入。注入点按类型与原始 EntityManagerFactory 定义匹配。

但是，@PersistenceContext 风格的共享 EntityManager 引用不能开箱即用地用于常规依赖注入。为了使其可用于 @Autowired 所需的基于类型的匹配，请考虑定义一个 SharedEntityManagerBean 作为 EntityManagerFactory 定义的伴侣。

<bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
	...
</bean>

<bean id="em" class="org.springframework.orm.jpa.support.SharedEntityManagerBean">
	<property name="entityManagerFactory" ref="emf"/>
</bean>

或者，您可以基于 SharedEntityManagerCreator 定义一个 @Bean 方法。

@Bean("em")
public static EntityManager sharedEntityManager(EntityManagerFactory emf) {
	return SharedEntityManagerCreator.createSharedEntityManager(emf);
}

在存在多个持久化单元的情况下，每个 EntityManagerFactory 定义都需要伴随一个相应的 EntityManager bean 定义，理想情况下使用与不同的 EntityManagerFactory 定义匹配的限定符，以便通过 @Autowired @Qualifier("…​") 区分持久化单元。

Spring 驱动的 JPA 事务

我们强烈建议您阅读 声明式事务管理（如果您还没有阅读），以获取有关 Spring 的声明式事务支持的更详细的介绍。

对于 JPA，推荐的策略是通过 JPA 的原生事务支持进行本地事务。Spring 的 JpaTransactionManager 提供了许多从本地 JDBC 事务中已知的功能（例如事务特定的隔离级别和资源级只读优化），针对任何常规 JDBC 连接池，无需 JTA 事务协调器和 XA 功能资源。

Spring JPA 还允许配置的 JpaTransactionManager 将 JPA 事务公开给访问相同 DataSource 的 JDBC 访问代码，前提是注册的 JpaDialect 支持检索底层的 JDBC Connection。Spring 为 EclipseLink 和 Hibernate JPA 实现提供了方言。有关 JpaDialect 的详细信息，请参见下一节。

对于 JTA 样式的实际资源连接的延迟检索，Spring 为目标连接池提供了一个相应的 DataSource 代理类：请参见LazyConnectionDataSourceProxy。这对于 JPA 只读事务特别有用，因为这些事务通常可以从本地缓存中处理，而不是访问数据库。

了解 JpaDialect 和 JpaVendorAdapter

作为一项高级功能，JpaTransactionManager 和 AbstractEntityManagerFactoryBean 的子类允许将自定义 JpaDialect 传递到 jpaDialect bean 属性中。JpaDialect 实现可以启用 Spring 支持的以下高级功能，通常以特定于供应商的方式

  • 应用特定的事务语义（例如自定义隔离级别或事务超时）

  • 检索事务性 JDBC Connection（用于公开给基于 JDBC 的 DAO）

  • 高级 PersistenceException 到 Spring 的 DataAccessException 的转换

这对于特殊的事务语义和高级异常转换特别有价值。默认实现 (DefaultJpaDialect) 不提供任何特殊功能，如果需要前面列出的功能，则必须指定相应的方言。

作为更广泛的提供程序适配设施，主要用于 Spring 的全功能 LocalContainerEntityManagerFactoryBean 设置，JpaVendorAdapter 将 JpaDialect 的功能与其他特定于提供程序的默认值相结合。指定 HibernateJpaVendorAdapter 或 EclipseLinkJpaVendorAdapter 是自动配置 Hibernate 或 EclipseLink 的 EntityManagerFactory 设置的最便捷方式。请注意，这些提供程序适配器主要设计用于与 Spring 驱动的交易管理一起使用（即，与 JpaTransactionManager 一起使用）。

有关其操作的更多详细信息以及它们如何在 Spring 的 JPA 支持中使用的信息，请参见JpaDialect 和JpaVendorAdapter javadoc。

使用 JTA 事务管理设置 JPA

作为 JpaTransactionManager 的替代方案，Spring 还允许通过 JTA 进行多资源事务协调，无论是在 Jakarta EE 环境中还是使用独立的事务协调器，例如 Atomikos。除了选择 Spring 的 JtaTransactionManager 而不是 JpaTransactionManager 之外，您还需要采取一些额外的步骤。

  • 底层的 JDBC 连接池需要是 XA 兼容的，并且与您的事务协调器集成。这在 Jakarta EE 环境中通常很简单，通过 JNDI 公开不同类型的 DataSource。有关详细信息，请参阅您的应用程序服务器文档。类似地，独立的事务协调器通常附带特殊的 XA 集成 DataSource 变体。同样，请查看其文档。

  • JPA EntityManagerFactory 设置需要为 JTA 配置。这是供应商特定的，通常通过特殊属性来指定，这些属性作为 jpaProperties 在 LocalContainerEntityManagerFactoryBean 上指定。在 Hibernate 的情况下，这些属性甚至特定于版本。有关详细信息，请参阅您的 Hibernate 文档。

  • Spring 的 HibernateJpaVendorAdapter 强制执行某些面向 Spring 的默认值，例如连接释放模式 on-close，它与 Hibernate 5.0 中的 Hibernate 自身默认值匹配，但在 Hibernate 5.1+ 中不再匹配。对于 JTA 设置，请确保将您的持久性单元事务类型声明为“JTA”。或者，将 Hibernate 5.2 的 hibernate.connection.handling_mode 属性设置为 DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT 以恢复 Hibernate 自身的默认值。有关相关说明，请参阅 Hibernate 中的虚假应用程序服务器警告。

  • 或者，考虑从您的应用程序服务器本身获取 EntityManagerFactory（即，通过 JNDI 查找而不是本地声明的 LocalContainerEntityManagerFactoryBean）。服务器提供的 EntityManagerFactory 可能需要在您的服务器配置中进行特殊定义（使部署不太可移植），但它已为服务器的 JTA 环境设置。

原生 Hibernate 设置和原生 Hibernate 事务用于 JPA 交互

原生 LocalSessionFactoryBean 设置与 HibernateTransactionManager 结合使用，允许与 @PersistenceContext 和其他 JPA 访问代码进行交互。Hibernate SessionFactory 本地实现 JPA 的 EntityManagerFactory 接口，Hibernate Session 处理程序本地是 JPA EntityManager。Spring 的 JPA 支持设施会自动检测原生 Hibernate 会话。

因此，这种原生 Hibernate 设置可以替代标准 JPA LocalContainerEntityManagerFactoryBean 和 JpaTransactionManager 组合，在许多情况下允许与 SessionFactory.getCurrentSession()（以及 HibernateTemplate）交互，以及 @PersistenceContext EntityManager 在同一个本地事务中。这种设置还提供了更强大的 Hibernate 集成和更多配置灵活性，因为它不受 JPA 引导合同的约束。

在这种情况下，您不需要HibernateJpaVendorAdapter配置，因为 Spring 的原生 Hibernate 设置提供了更多功能（例如，自定义 Hibernate Integrator 设置、Hibernate 5.3 bean 容器集成以及对只读事务的更强优化）。最后但并非最不重要的一点是，您还可以通过LocalSessionFactoryBuilder表达原生 Hibernate 设置，与@Bean样式配置无缝集成（不涉及FactoryBean）。

LocalSessionFactoryBean和LocalSessionFactoryBuilder支持后台引导，就像 JPA 的LocalContainerEntityManagerFactoryBean一样。有关介绍，请参见后台引导。

在LocalSessionFactoryBean上，这可以通过bootstrapExecutor属性实现。在程序化的LocalSessionFactoryBuilder上，重载的buildSessionFactory方法接受一个引导执行器参数。