版本升级迁移指南

从 Vert.x 4 升级迁移至 Vert.x 5 指南

本指南详细介绍了 Eclipse Vert.x 5 版本中的重大架构更新、破坏性变更与迁移指引。你可以参考本文档将现有的 Vert.x 4.x 应用程序平滑升级到 Vert.x 5。本文档全面梳理了新特性、废弃声明以及移除淘汰的功能组件。

根据你应用程序中所实际使用的模块，你可以查阅对应小节以了解 Vert.x 5 中的具体变更。

关于 Vert.x

Vert.x 是用于在 Java 虚拟机（JVM）上构建响应式、非阻塞且全异步应用程序的轻量级工具包。它包含多个核心组件，帮助你轻松创建符合响应式宣言的分布式系统。在设计之初，Vert.x 即天然面向云原生生态。

得益于其全异步非阻塞的高性能基石，Vert.x 广泛适用于高并发消息吞吐、大规模实时流处理、高吞吐 HTTP 服务治理等海量并发技术场景。

Vert.x 5 核心重大变更

本节阐述了 Vert.x 5 与 4.x 版本之间的根本性设计与架构差异。

处理废弃与移除的 API

在 Vert.x 5 中，部分长期废弃的特性与接口已被正式移除。在开始将应用程序迁移至 Vert.x 5 之前，请务必核对废弃与移除清单：

部分 API 早在 Vert.x 4.x 的某个维护版本中即已声明为 @Deprecated，并在当时提供了功能等价的新推荐 API；
这些被废弃的历史旧 API 在 Vert.x 5 中已被全量彻底移除。

如果你的业务代码仍在使用这些过时方法，建议先在 Vert.x 4 项目中根据 Java 编译器的警告提示逐步替换为推荐的新方法，确保编译零警告后，再无缝切换至 Vert.x 5 依赖。

组件淘汰与日落计划 (Sunsets & Removals)

部分旧组件在 5 中进入日落淘汰期（Sunsetting）。这意味着它们在整个 5.x 的生命周期内依然保持技术维护与可用，但官方已不再推荐使用，因为社区已经提供了更为现代化的高性能替代方案。这些组件将在下一代主版本（Vert.x 6）中被彻底删除：

进入日落期的组件	推荐替代方案
gRPC Netty	Vert.x gRPC Client 与 Server 原生模块
传统 JDBC API	基于 SQL Client API 的 JDBC 实现驱动
Service Discovery 服务发现	Vert.x Service Resolver（原生服务解析器）
RxJava 2	SmallRye Mutiny 或 RxJava 3
OpenTracing	OpenTelemetry
Vert.x Unit	Vert.x JUnit 5

进入日落期的组件

推荐替代方案

gRPC Netty

Vert.x gRPC Client 与 Server 原生模块

传统 JDBC API

基于 SQL Client API 的 JDBC 实现驱动

Service Discovery 服务发现

Vert.x Service Resolver（原生服务解析器）

RxJava 2

SmallRye Mutiny 或 RxJava 3

OpenTracing

OpenTelemetry

Vert.x Unit

Vert.x JUnit 5

以下为在 4.x 时期已宣布日落、并在 5 中已被彻底移除的组件清单：

已移除组件	替代方案
Vert.x Sync (基于 Quasar 纤程)	Java 21+ 虚拟线程 (Virtual Threads)
Service Factories	无
Maven Service Factory	无
HTTP Service Factory	无
Vert.x Web OpenAPI	Vert.x Web OpenAPI Router

已移除组件

替代方案

Vert.x Sync (基于 Quasar 纤程)

Java 21+ 虚拟线程 (Virtual Threads)

Service Factories

无

Maven Service Factory

无

HTTP Service Factory

无

Vert.x Web OpenAPI

Vert.x Web OpenAPI Router

全面拥抱 Future 异步模型

Vert.x 4 为了兼容 Vert.x 3 的老代码，采用了 Callback 回调与 Future 并存的双重混合 API 模型。每一个异步方法都同时存在两个重载：

public interface HttpClient {

   // Future 版本
   Future<HttpClientRequest> request(RequestOptions request);

   // Callback 回调版本
   void request(RequestOptions request, Handler<AsyncResult<HttpClientRequest>> callback);
}

而在 Vert.x 5 中，回调重载被全量彻底移除，全框架统一仅保留 Future 模型：

public interface HttpClient {

   // 仅保留 Future 版本
   Future<HttpClientRequest> request(RequestOptions request);
}

如果你仍有基于回调编写的遗留代码，只需简单调用 future.onComplete(ar → …) 即可无损迁移！

广泛采用 Builder 构建器模式

Vert.x 5 广泛引入了 Builder 构建器设计模式，将传统的静态选项配置（Options）与动态运行时对象实例的装配彻底解耦。

在 Vert.x 4.x 中自定义集群管理器通常依赖复杂的嵌套 Options：

Vert.x 4 中的实例配置方式

Future<Vertx> future = Vertx.clusteredVertx(options.setClusterManager(clusterManager));

而在 Vert.x 5 中，构建器模式提供了极其清晰、链式且结构鲜明的方法：

Vert.x 5 中的 Builder 构建方式

Future<Vertx> f = Vertx
  .builder()
  .with(options)
  .withClusterManager(clusterManager)
  .buildClustered();

这种优雅的 Builder 模式已全面应用于 Vert.x 5 各大核心组件中。

核心组件细节变更

移除 vertx 独立命令行工具

全局的 vertx 独立命令行可执行工具在 Vert.x 5 中已被正式移除。

Vert.x 团队希望将技术重心聚焦于现代主流的应用交付范式：通过标准构建工具将应用编译并打包为可执行 Uber-JAR（Fat-JAR）或直接生成容器镜像。

Maven 用户：推荐使用 Vert.x Maven Plugin，不仅支持标准打包，还提供代码热重载开发模式（mvn vertx:run）；
Gradle 用户：推荐使用 Vert.x Gradle Plugin，支持自动化依赖与极速打包。

vertx-cli 命令行解析库日落淘汰

vertx-cli 库在 Vert.x 5 中已正式进入日落淘汰期。

该库原先主要供已被移除的 vertx 命令行脚本自身使用。对于需要编写命令行工具的业务系统，强烈推荐选用 Java 生态中功能更为全面、成熟且被普遍采纳的现代化 CLI 框架，例如功能卓越的 Picocli。

Vert.x Core 核心模块变更

实例构建与定制 (Builder Pattern)

Vert.x 5 Core 核心实例创建全面推荐使用 Vertx.builder() 构建器模式：

Vertx vertx = Vertx.builder()
  .with(new VertxOptions().setWorkerPoolSize(40))
  .build();

HTTP 相关破坏性变更与调整

移除无时间单位的 HTTP 连接关闭重载

在 Vert.x 5 中，所有关于优雅关闭连接的重载方法均要求显式传递时间数值与 TimeUnit，避免单位歧义。

HTTP 响应与请求 Cookie 映射优化

移除了原先性能较差的同步 Cookie Map 拷贝方法，推荐使用轻量且经过缓存优化的 request.cookies() 视图集合。

HttpClientRequest 设置超时方法重命名

方法 setTimeout 已统一重命名为更贴合真实网络语义的 setIdleTimeout（空闲超时），明确该时间代表连接未收到网络字节流时的空闲超时阈值。

移除 HttpClient 中的旧 WebSocket 声明

直接在 HttpClient 上的旧 WebSocket 连接方法已被移除，统一使用专用的 WebSocketClient 独立客户端进行连接与管理。

HTTP 流式方法返回值由 Fluent 链式调整为 Future [[_http_stream_async_methods_returns_now_a_future_instead of_being_fluent]]

在 Vert.x 4 中，部分异步流式方法返回当前流自身（Fluent 链式）；在 Vert.x 5 中，这些涉及异步网络 I/O 的方法（如 end()、write()）全量改为返回 Future<Void>，以便调用方能精准感知并等待网络数据完全刷入 TCP 缓冲区。

Future 核心演进

移除 CompositeFuture 原始类型

移除了 CompositeFuture.all(Future…) 返回未参数化类型的不安全重载，全量使用类型安全的泛型聚合方法。

废弃接收函数的 eventually 重载

Future.eventually 契约统一，仅接收在异步完成或失败时执行的清理操作，提升 API 表达的单一职责性。

工作线程 Verticle (Worker Verticles)

移除了部署选项中历史过时的 worker 布尔标记，统一使用 ThreadingModel.WORKER 显式声明调度线程模型：

DeploymentOptions options = new DeploymentOptions()
  .setThreadingModel(ThreadingModel.WORKER);

事件总线 (Event Bus) 变更

在 Vert.x 5 中，优化了 Event Bus 背压机制与消息缓冲区的动态调整逻辑，保证在高吞吐突发流量下消费者不会发生内存无序膨胀。

文件系统 (File System) 变更

在文件系统异步删除操作中，移除了容易引发歧义的布尔参数重载，统一明确为 fs.deleteRecursive(path) 与 fs.delete(path)。

Vert.x Auth 认证鉴权模块变更

在 Vert.x 5 中，Vert.x 认证鉴权体系移除了历史遗留的直接回调接口，全量统一为返回 Future 的响应式 API。

用户凭证校验与权限查询操作现在均返回标准 Future<User> 与 Future<Boolean>，与响应式流及链式组合更加契合。

Vert.x Kotlin 模块变更

在 Vert.x 5 中，随着 Java 核心全量切向 Future 模型，Kotlin 协程扩展库（vertx-lang-kotlin-coroutines）也进行了重大精简与现代化演进：

原先大量针对回调函数生成的 awaitResult { … } 辅助工具现已全量推荐替换为针对 Future 的直接挂起等待：future.await()；
废弃并移除了老旧的 Channel 桥接包装，更加紧密地围绕 Kotlin 官方标准协程库与响应式 Flow 进行构建。

Vert.x gRPC 模块变更

在 Vert.x 5 中，原先基于老旧 Netty 独立存根的 gRPC 模块已被现代化的全新 gRPC 体系完全取代：

提供了原生的 vertx-grpc-client 与 vertx-grpc-server；
完美支持现代 HTTP/2 原生双向流与 gRPC-Web 浏览器端直连；
支持纯非阻塞的上下文感知流式传输与背压控制机制。

Vert.x Web 模块变更

Vert.x Web 在 5 中重点优化了路由处理与现代 OpenAPI 契约整合：

移除了已废弃的 vertx-web-openapi，全面推荐使用高性能的全新 vertx-web-openapi-router；
路由处理器中的异步拦截逻辑全量支持 Future 链式返回；
增强了基于 Cookie 与 Session 的企业级防篡改安全保护。

Vert.x Web Client 模块变更

Web Client 在 5 中全面拥抱了基于 Builder 的流式请求装配：

移除了所有带有回调 Handler 的冗余重载方法，统一为 send().compose(…) 异步管道；
支持针对重定向、超时重试以及认证凭据的主动拦截器链（Interceptors）；
优化了连接池闲置连接的自动化回收与高并发吞吐表现。

Vert.x Web GraphQL 模块变更

在 Vert.x 5 中，升级适配了最新的 GraphQL Java 核心引擎，并优化了在 Event Loop 上执行非阻塞数据加载器（DataLoader）的并发调度性能。

Vert.x Web Validation 校验模块变更

移除了与老旧 JSON 校验体系绑定的历史废弃类，全面拥抱最新的 JSON Schema 规范，并支持请求参数的声明式强类型校验与格式转换。

Vert.x SQL Client 响应式数据库客户端变更

在 Vert.x 5 中，传统阻塞式的 vertx-jdbc-client 正式被基于 SQL Client API 的现代化实现所取代：

所有关系型数据库客户端（PostgreSQL、MySQL、MSSQL、Oracle、DB2）拥有完全统一的连接池与事务语义；
事务管理方法全面支持基于 Future 的函数式模板执行（pool.withTransaction(client → …)）；
引入了基于 SQL Client Templates 的自动类型推导与结果集对象映射。

Vert.x Redis Client 模块变更

在 Vert.x 5 中，Redis 客户端进行了底层性能架构重构：

优化了 RESP3 协议的零拷贝解析性能；
提供了对 Redis Cluster 集群拓扑动态变更与主从自动切换的毫秒级感知；
管道化（Pipelining）请求与发布/订阅（Pub/Sub）模式在事件总线上的集成更加低延迟。

Vert.x RabbitMQ Client 模块变更

4.x 版本的 RabbitMQ 客户端对 RabbitMQ 底层协议进行了过于高层的抽象封装，导致许多现代 RabbitMQ 高级特性（例如定制 Exchange、流式消费等）无法实现。

因此，Vert.x 5.0 对 RabbitMQ 客户端进行了彻底重构，提供了崭新且更为灵活强大的 API。

连接建立方式演化

在 4.x 中，客户端使用单个 RabbitMQClient 将连接（Connection）与信道（Channel）紧密耦合在一起。而在 5.0 中，这两者在设计上完全解耦，一个底层 TCP 连接上可以轻松多路复用开启多个独立的并发 Channel 信道。

5.0 的 RabbitMQChannel 在语义上最为贴近原先 4.x 的客户端：

// 5.0 全新连接与信道创建方式
RabbitMQOptions config = new RabbitMQOptions();
config.setUri("amqp://brokerhost/vhost");
config.setUser("guest");
config.setPassword("guest");

RabbitMQClient.connect(vertx, config)
  .compose(connection -> {
    return connection.createChannel();
  })
  .onSuccess(channel -> {
    // 成功获取独立信道并开展消费与投递
  });

Vert.x 断路器 (Circuit Breaker) 变更

断路器模块在 5 中重构了对异步失败的熔断统计逻辑：

统一接入 Future 返回契约；
允许开发者更精准地配置熔断重试策略与降级兜底函数（Fallback）；
提供了更丰富的 Micrometer 监控指标暴露。

Vert.x 健康检查 (Health Checks) 变更

健康检查模块在 5 中优化了探针注册流程与云原生标准：

与 Kubernetes 存活探针（Liveness）与就绪探针（Readiness）无缝映射；
检查结果以结构化 JSON 与异步 Future 呈现，杜绝探针自身阻塞主事件循环。

全面支持 Prometheus、OpenTelemetry、InfluxDB 等多种现代指标收集后端；
默认提供了精细化的 Event Loop 延迟耗时直方图分布（Timer Histograms）；
对 HTTP 连接池与 SQL 连接池的活跃度、等待队列长度实现了开箱即用的实时透视。

移除了冗余的历史回调契约，原生生成返回 Future 的纯正异步接口代理；
支持在微服务间通过 Event Bus 进行零样板代码的强类型 RPC 调用。

Vert.x Hazelcast 集群管理器变更

在 Vert.x 5 中：

升级适配了最新的 Hazelcast 5.x 稳定分支；
在 macOS 模块路径下支持通过显式 TCP 配置替代不稳定的组播自动发现（Multicast）。

从 Vert.x 3 升级迁移至 Vert.x 4 指南