Hibernate Reactive：让 Hibernate 在响应式世界里跑起来

hibernate-reactive 在 GitHub 上拿到 465 颗 Star。

Hibernate 团队出品的这个项目，把传统 Hibernate ORM 接到了响应式数据库驱动上，让 Java 开发者能用非阻塞的方式操作数据库。它能在任何普通 Java 程序里用，重点适配 Quarkus 和 Vert.x 这两类响应式框架。

它解决什么问题

写过响应式应用的人都知道，HTTP 层可以用 Vert.x 或 Quarkus 做成全异步，但一进数据库层就破功。JDBC 是阻塞的，Hibernate ORM 依赖 JDBC，整条调用链到这一步就得开线程池硬扛，吞吐量掉下来。

Hibernate Reactive 干的事就是把 ORM 这一层重写成响应式风格。底层数据库驱动换成 Vert.x 的 Reactive SQL Client，上层 API 返回的是 CompletionStage 或 Uni/Multi，不再阻塞调用线程。Hibernate 多年积累的实体映射、关联、缓存、查询能力都保留着。

支持哪些数据库

目前支持的数据库不少，主流的几个都覆盖了：

• PostgreSQL 18
• MySQL 9
• MariaDB 12
• Db2 12
• CockroachDB v26
• MS SQL Server 2025
• Oracle 23

每款数据库对应一个 Vert.x Reactive SQL Client 实现。Hibernate ORM 版本要求 7.4，Vert.x Reactive SQL Client 5.1。

Java 运行时方面，测试覆盖到 Java 17、21、26 三个 LTS 版本。

在哪些场景里用

项目本身是个库，但定位很明确，重点服务 Quarkus 和 Vert.x 这两个生态。

Quarkus 那边直接有 Hibernate Reactive 扩展，配合 RESTEasy Reactive 或者 Panache Reactive 都能用。Panache Reactive 是基于它的 ActiveRecord 风格 API，写起来挺干净。

Vert.x 用户可以参考 how-to.vertx.io 上的指南接入。如果你直接用Hibernate Reactive，配 Vert.x Reactive SQL Client 起 session 就行。

项目里还带了一组示例：session 范例演示基本 CRUD，native-sql 范例展示原生查询和 stateless session 怎么用。

试用方式

不想 clone 仓库的话，可以用 JBang 直接跑示例：

jbang alias list hibernate/hibernate-reactive
jbang example@hibernate/hibernate-reactive

想生成可复现的测试用例也行，项目提供了针对每个数据库的复现模板：

jbang init --template=pg-reproducer pgTest.java
jbang pgTest.java

跑 Quarkus 项目的话，去 code.quarkus.io 勾选 Hibernate Reactive 扩展生成脚手架，最快几分钟就能起一个能跑的项目。

跑测试

测试默认用 Testcontainers 在 Docker 里起数据库实例，一行命令就能跑：

./gradlew test

指定数据库，用 -Pdb=pg 这样的参数，或者直接走 dedicated task，比如 ./gradlew testDbMySQL。

不想用 Testcontainers 也行，加 -PskipTestcontainers，自己先建好库和账号即可。文档里给了 PostgreSQL 和 MySQL 的创建脚本，照抄就行。用 Podman 的用户照着项目根目录的 podman.md 走。

还差什么

项目方说在追平 Hibernate ORM 全部特性，目前有几个小限制：@Source 注解和 @CollectionId 注解暂不支持，Db2 上的自动 schema 更新和校验做不了，@Lob 注解在 Db2 上不可用。

这些点对一般业务影响不大。如果你的项目已经押注响应式栈，又想继续用 Hibernate 的映射能力，hibernate-reactive 是绕不开的一环。

这些点对一般业务影响不大。如果你的项目已经押注响应式栈，又想继续用 Hibernate 的映射能力，hibernate-reactive 是绕不开的一环。