Hibernate Reactive 2.4.0.Final 参考文档

将以下依赖项添加到您的项目

其中 {version} 是您正在使用的 Hibernate Reactive 版本。

您还需要为数据库添加 Vert.x 反应式数据库驱动程序的依赖项，以下列出了一些选项

其中 {vertxSqlClientVersion} 是与您正在使用的 Hibernate Reactive 版本兼容的 Vert.x 版本。

您不需要依赖数据库的 JDBC 驱动程序。

可选地，您还可以添加以下任何其他功能

如果您想使用域级延迟获取，您还可以将 Hibernate 字节码增强器 添加到您的 Gradle 构建中。

示例程序中包含一个示例 Gradle 构建。

Hibernate Reactive 通过标准 JPA persistence.xml 文档进行配置，该文档必须像往常一样放置在 /META-INF 目录中。

示例程序中包含一个示例 persistence.xml 文件。

唯一真正特定于 Hibernate Reactive 的必需配置是持久性 <provider> 元素，它必须是显式的

否则，配置几乎完全透明——您可以像通常配置 Hibernate ORM 核心一样配置 Hibernate Reactive。

就像在常规 JPA 中一样，您应该在 persistence.xml 中列出您的实体类

可以在 Hibernate ORM 文档 中找到 Hibernate 识别的所有配置属性的完整列表。您永远不需要触摸这些属性中的大多数。您在此阶段需要的属性是以下三个

这些配置属性的名称中包含 jdbc，但当然 Hibernate Reactive 中没有 JDBC，这些只是 JPA 规范定义的传统属性名称。特别是，Hibernate Reactive 本身会解析和解释 JDBC URL。

Vert.x 数据库客户端内置连接池和准备语句缓存。您可能想控制连接池的大小

我们将在后面学习有关更高级的连接池调整，在 调整 Vert.x 池 中。

您可以让 Hibernate Reactive 从您在 Java 代码中指定的映射注释中推断您的数据库模式，并在初始化时导出模式，方法是指定以下一个或多个配置属性

此功能对于测试非常有用。

模式导出使用阻塞操作，因此在使用它时，启动工厂可能需要特殊处理。未能这样做会导致异常

您可以使用 executeBlocking 解决此问题

要查看发送到数据库的生成的 SQL，可以执行以下操作

例如，如果您使用的是 Log4J 2（如上文中的 可选依赖项），请将以下行添加到您的 `log4j2.properties` 文件中

示例 `log4j2.properties` 文件包含在示例程序中。

您可以通过启用以下一个或两个设置来使记录的 SQL 更具可读性

以下属性对于最小化您需要在 `@Table` 和 `@Column` 注释中显式指定的 信息量非常有用，我们将在下面 映射实体类 中讨论。

默认情况下，SQL Server 的 `char` 和 `varchar` 类型不兼容 Unicode 数据。因此，如果您使用的是 SQL Server，您可能需要强制 Hibernate 使用 `nchar` 和 `nvarchar` 类型。

我们在这里不会过多地谈论实体类，仅仅是因为 Hibernate Reactive 中映射实体类的原则，以及您将使用的实际映射注释，都与常规 Hibernate ORM 和 JPA 的其他实现完全相同。

例如

您可以自由地混合和匹配

有关对象/关系映射注释的完整列表，请参阅 Hibernate ORM 文档。Hibernate Reactive 已经支持大多数映射注释，尽管目前仍存在一些限制。

在非 Quarkus 环境中使用 Hibernate Reactive 时，您需要按照通常的 JPA 约定编写实体类，这些约定要求

从实体类外部访问持久性字段是非法的。因此，对持久性字段的外部访问必须通过实体类定义的 getter 和 setter 方法来中介。

当您在 Quarkus 中使用 Hibernate Reactive 时，这些要求会放宽，如果您愿意，可以使用公共字段而不是 getter 和 setter。

实体类应该重写 `equals()` 和 `hashCode()`。Hibernate 或 JPA 的新手经常对 `hashCode()` 中应该包含哪些字段感到困惑，因此请牢记以下原则

将任何不可变的、非生成的字段包含在哈希码中是可以的。

也就是说，基于实体的生成标识符的 `equals()` 和 `hashCode()` 的实现可以在您小心的情况下起作用。

请注意，即使您已经确定了自然键，我们仍然建议在外键中使用生成的代理键，因为这会使您的数据模型更加容易更改。

Hibernate Reactive 的功能与普通 Hibernate 偏离的一个领域是 ID 生成领域。为与 Hibernate ORM 和 JDBC 一起使用而编写的自定义标识符生成器将无法在响应式环境中使用。

JPA 规范定义的标准 ID 生成策略可以通过以下注解进行自定义

例如，序列 ID 生成可以这样指定

您可以在 JPA 规范中找到更多信息。

如果您有非常特殊的需求，可以查看 ReactiveIdentifierGenerator 的 Javadoc，了解如何实现您自己的自定义反应式标识符生成器。

基于 UserType 接口的 Hibernate 自定义类型针对与 JDBC 一起使用，并且依赖于 JDBC 定义的接口。因此，Hibernate Reactive 提供了一个适配器，它向 UserType 实现公开 JDBC 的部分实现。

因此，某些现有的 UserType 实现将在 Hibernate Reactive 中起作用，具体取决于它们依赖的 JDBC 功能。

您可以通过使用 Hibernate @Type 注解来注释实体类的一个字段，来指定自定义类型。

任何 JPA AttributeConverter 都可以在 Hibernate Reactive 中使用。例如

您需要使用以下一个或两个注解

您可以在这些注解的 Javadoc 和 JPA 规范中找到更多信息。

当您使用 Hibernate Reactive 编写持久化逻辑时，您大多数时候都在使用反应式 Session。为了让新用户更加困惑，反应式 Session 及其相关接口都有两种形式

您需要决定要使用哪个 API！

以下是在使用 Hibernate Reactive 时一直需要的反应式流上最重要的操作

在本介绍中，我们的代码示例通常使用 Mutiny。如果您更熟悉 CompletionStage，您可以参考上表来帮助您理解代码。

当我们在本文档中使用术语反应式流时，我们的意思是

它是为了服务特定请求、事务或工作单元而由程序构建的。

无论您决定什么，获取反应式会话的第一步是获取 JPA EntityManagerFactory，就像您通常在普通的 JPA 中一样，例如，通过调用

现在，unwrap() 反应式 SessionFactory。如果您想使用 CompletionStage 来链接反应式操作，请请求 Stage.SessionFactory

或者，如果您更喜欢使用基于 Mutiny 的 API，则 unwrap() 类型 Mutiny.SessionFactory

可以从生成的反应式 SessionFactory 获取反应式会话。

持久化操作通过反应式 Session 对象公开。了解此接口的大多数操作都是非阻塞的，并且永远不会同步执行针对数据库的 SQL 至关重要。属于单个工作单元的持久化操作必须在单个反应式流内通过组合进行链接。

还要记住，Hibernate 会话是一个轻量级对象，应该在单个逻辑工作单元内创建、使用，然后丢弃。

要从 SessionFactory 获取反应式 Session，请使用 withSession()

生成的 Session 对象会自动与当前反应式流关联，因此在给定流中嵌套调用 withSession() 会自动获取相同的共享会话。

或者，您可以使用 openSession()，但您必须记住在完成时 close() 会话。并且您必须非常小心，只能从一个 Vert.x 上下文内访问每个会话。（有关更多信息，请参阅 会话和 Vert.x 上下文）。

Session 接口具有与 JPA EntityManager 的方法同名的函数。您可能已经熟悉 JPA 定义的以下会话操作

如果您不熟悉这些操作，请不要绝望！它们的语义在 JPA 规范和 API 文档中定义，并在无数文章和博文中进行了说明。但是，如果您已经有一些使用 Hibernate 或 JPA 的经验，那么您就来了！

现在，这是 Hibernate Reactive 与众不同的地方：在反应式 API 中，这些方法中的每一个都通过 Java CompletionStage（或 Mutiny Uni）以非阻塞方式返回其结果。例如

另一方面，没有有意义的返回值的方法只返回 CompletionStage<Void>（或 Uni<Void>）。

使用反应式流时的一个非常常见的错误是忘记链接“类 void”方法的返回值。例如，在以下代码中，flush() 操作从未执行，因为 invoke() 不会将其返回值链接到流的顶端。

所以请记住

以下代码中也存在相同的问题，但这次是 remove() 从未被调用

如果您已经有一些使用反应式编程的经验，那么这里没有什么新东西需要学习。但是，如果您是反应式编程的新手，请注意您将以某种形式至少犯一次这个错误！

自然，Session 接口是 Query 实例的工厂，它允许您设置查询参数并执行查询和 DML 语句

该 createQuery() 方法生成一个反应式 Query，允许异步执行 HQL/JPQL 查询，始终通过 CompletionStage（或 Uni）返回其结果

Query 接口定义了以下重要操作

对于 JPA 标准查询，您必须首先使用 SessionFactory.getCriteriaBuilder() 获取 CriteriaBuilder，然后使用 Session.createQuery() 执行查询。

在 Hibernate ORM 中，当第一次在会话内访问关联时，延迟关联会透明地获取。另一方面，在 Hibernate Reactive 中，延迟关联获取是一个异步过程，它通过 CompletionStage（或 Uni）生成结果。

因此，延迟获取是一个名为 fetch() 的显式操作，它是 Stage 和 Mutiny 的一个静态方法

当然，如果您急切地获取关联，则无需执行此操作。

有时您可能需要链接对 fetch() 的多次调用，例如

类似地，字段级延迟获取（一项高级功能，仅在与 Hibernate 的可选编译时字节码增强器结合使用时才支持）也是一项显式操作。

要声明延迟字段，我们通常使用 JPA @Basic 注释

声明为 @OneToOne(fetch=LAZY) 的可选一对一关联也被视为字段级延迟。

仅当我们通过调用 fetch() 操作的重载版本显式请求时，才会获取延迟字段

请注意，要获取的字段由 JPA 元模型 Attribute 标识。

withTransaction() 方法在数据库事务范围内执行工作。

在事务结束时，会话会自动刷新。

对于给定的 Session 对象，对 withTransaction() 的嵌套调用发生在相同的共享事务上下文中。但是，请注意，事务仅是 *资源本地* 事务，委托给底层的 Vert.x 数据库客户端，并且不跨多个数据源，也不与 JPA 容器管理的事务集成。

为了方便起见，还有一个方法可以在一次调用中打开会话并启动事务

这可能是大多数情况下最方便使用的方法。

当您使用 withSession() 或 withTransaction() 创建会话时，它会自动与当前 Vert.x 本地上下文 关联，并在本地上下文中传播，如上所述 获取反应式会话。并且您只允许从拥有此本地上下文的线程使用会话。如果您搞砸了，并在不同的线程中使用它，您可能会看到此错误

另一方面，如果您使用 openSession()，您将不得不自己管理会话和上下文之间的关联。现在，原则上这很简单，但您会惊讶于人们出错的频率。

许多用户对这种限制感到惊讶。但我们坚持认为这完全是自然的。从您作为会话用户角度来看，会话的原子操作是一个方法，例如 flush()、find() 或 getResultList()。任何一种方法都可能导致 *与数据库的多次交互*。在这些交互之间，会话根本没有处于定义良好的状态。反应流是一种线程，期望反应式编程在闪烁的魔法尘埃中消失您的并发问题是不合理的。这些事情不是这样运作的。

例如，我敢打赌您希望能够编写这样的代码

好吧，我们很抱歉，但这是不允许的。并行反应流不能共享会话。每个流必须有自己的会话。

如果您需要在 Vert.x 上下文的范围内运行一段代码，但当前线程未与 Context 关联怎么办？一种解决方案是使用 getOrCreateContext() 获取 Vert.x Context 对象，然后调用 runOnContext() 在该上下文中执行代码。

在传递给 runOnContext() 的代码块内，您将能够使用与上下文关联的 Hibernate Reactive 会话。

VertxInstance 服务定义了 Hibernate Reactive 如何获取 Vert.x 的实例。默认实现只在第一次需要时创建它。但是，如果您的程序需要控制 Vert.x 实例的创建方式或获取方式，您可以覆盖默认实现并提供您自己的 VertxInstance。让我们考虑这个例子

注册此实现的一种方法是通过编程方式配置 Hibernate，例如

或者，您可以实现 ServiceContributor 接口。

要注册此 ServiceContributor，请将名为 org.hibernate.service.spi.ServiceContributor 的文本文件添加到 /META-INF/services/ 中。

在 基本配置 中，我们已经看到了如何设置 Vert.x 数据库连接池的大小。在进行性能调整时，您可以通过以下配置属性进一步自定义池和预处理语句缓存

最后，对于更高级的情况，您可以编写自己的代码来通过实现 SqlClientPoolConfiguration 来配置 Vert.x 客户端。

几乎无需任何工作即可提高某些事务性能的一种简单方法是打开自动 DML 语句批处理。批处理仅在程序在单个事务中对同一表执行许多插入、更新或删除的情况下才有帮助。

您所需要做的就是设置一个属性

（再次，此属性的名称中包含 jdbc，但 Hibernate Reactive 将其重新用于反应式连接。）

在 ORM 中实现高性能意味着最大限度地减少对数据库的往返次数。每当您使用 Hibernate 编写数据访问代码时，这个目标都应该牢记在心。ORM 中最基本的经验法则是

毫无疑问，Java 程序中数据访问代码性能低下最常见的原因是 *N+1 选择* 问题。在这里，N 行的列表在初始查询中从数据库中检索，然后使用 N 个后续查询获取相关实体的关联实例。

Hibernate 提供了几种策略来有效地获取关联并避免 N+1 选择

其中，您几乎应该始终使用外连接获取。批量获取和子查询获取仅在很少的情况下有用，在这种情况下，外连接获取会导致笛卡尔积和巨大的结果集。不幸的是，外连接获取与延迟获取根本无法实现。

从这个提示可以得出，您不应该经常使用 Stage.fetch() 或 Mutiny.fetch()！

现在，我们并不是说关联应该默认映射为急切获取！那将是一个糟糕的主意，会导致简单的会话操作获取整个数据库！因此

听起来这个提示与上一个提示相矛盾，但事实并非如此。它是在说，您必须在需要时，在需要的地方明确指定关联的急切获取。

如果您在某些特定事务中需要急切获取，请使用

有关关联获取的更多信息，请参阅 Hibernate ORM 文档。

减少数据库访问次数的一种经典方法是使用二级缓存，允许在会话之间共享缓存数据。

Hibernate Reactive 支持不执行阻塞 I/O 的二级缓存实现。

配置 Hibernate 的二级缓存是一个相当复杂的话题，超出了本文档的范围。但是，如果它有所帮助，我们正在使用以下配置测试 Hibernate Reactive，该配置使用 EHCache 作为缓存实现，如上面的 可选依赖项 中所示。

如果您使用 EHCache，您还需要包含一个 ehcache.xml 文件，该文件显式配置属于您的实体和集合的每个缓存区域的行为。

有关二级缓存的更多信息，请参阅 Hibernate ORM 文档。

实体实例不会在不再需要时自动从会话缓存中逐出。（就这方面而言，会话缓存与二级缓存完全不同！）相反，它们会保留在内存中，直到它们所属的会话被您的程序丢弃。

detach() 和 clear() 方法允许您从会话缓存中删除实体，使其可用于垃圾回收。由于大多数会话都很短命，因此您不会经常需要这些操作。如果您发现自己认为在某种情况下需要它们，您应该认真考虑另一种解决方案：无状态会话。

Hibernate 的一个鲜为人知的特性是 StatelessSession 接口，它提供了一种面向命令的、更基础的方法来与数据库交互。

您可以从 SessionFactory 获取反应式无状态会话

无状态会话

对于无状态会话，您始终使用分离的对象。因此，编程模型略有不同

在某些情况下，这使得无状态会话更容易使用，但需要注意的是，无状态会话更容易受到数据别名影响，因为很容易获得两个不相同的 Java 对象，它们都代表数据库表的同一行。

特别是，没有持久化上下文意味着您可以安全地执行批量处理任务，而不会分配大量的内存。使用 StatelessSession 消除了调用以下操作的需要

使用无状态会话时，您应该注意以下其他限制

最后，我们在上面没有提到的行为负载方面是行级数据争用。当许多事务尝试读取和更新相同数据时，程序可能会由于锁升级、死锁和锁获取超时错误而变得无响应。

Hibernate 中有两种基本的数据并发方法

在 Hibernate 社区中，使用乐观锁非常普遍，Hibernate 使其变得极其容易。

也就是说，悲观锁也确实有其用途，它有时可以降低事务回滚的概率。

因此，反应式会话的 find()、lock() 和 refresh() 方法接受可选的 LockMode。您也可以为查询指定 LockMode。锁模式可用于请求悲观锁，或自定义乐观锁的行为