进阶与底层架构

Vert.x 模块化指南 (JPMS)

从 5 版本开始，Vert.x 全面支持利用 Vert.x 技术栈构建与运行基于 Java 平台模块系统 (JPMS) 的模块化应用程序与微服务。

本文档旨在指导开发者如何基于 Vert.x 构建、打包与运行模块化 Java 应用。

核心概念与定义

我们在本文中沿用 JPMS 规范术语清单 中的标准定义：

  • 命名模块（Named module）

  • 显式模块（Explicit module）

  • 自动模块（Automatic module）

JPMS 成熟度模型

Vert.x 致力于提供最高级别的 JPMS 规范支持（参见 Java 模块成熟度模型）。

绝大多数 Vert.x 核心组件均达到了成熟度 Level 3 标准，并提供了完整的显式模块描述符（module-info）。仅有极少数第三方适配模块因上游传递依赖包拆分（Split Package）等客观限制被暂时归为自动模块。

原生网络传输 (Native Transports)

Vert.x 模块化体系完整支持 Netty 原生传输层（如 Linux epoll、macOS kqueue、io_uring）。

模块 io.netty.transport.classes.${native.detected.transport} 是编译时必需依赖，因为它包含了具体的传输抽象类。

而模块 io.netty.transport.${native.transport}.${os.name}.${os.detected.arch} 包含原生 C 共享动态链接库，仅在运行时需要。

你可以在 JVM 启动命令中添加参数：--add-modules io.netty.transport.classes.${native.transport},io.netty.transport.${native.transport}.${os.detected.name}.${os.detected.arch}。

或者，你也可以直接将它们声明进自己的模块描述符中（即使你的应用代码本身未显式直接调用它们）。这通常会促使构建工具在运行时自动引入它们，不过这会将你的模块绑定到特定的操作系统/CPU 架构：

// 添加到 module-info.java
requires io.netty.transport.classes.kqueue;
requires io.netty.transport.kqueue.osx.aarch_64;

你可以在 Vert.x 示例集合中参考 原生传输与 OpenSSL 模块化示例。

OpenSSL 支持

Vert.x 模块化体系支持 OpenSSL 硬件加速。

模块 io.netty.tcnative.classes.openssl 是必需的编译时模块，包含了 OpenSSL Netty 桥接类。

模块 io.netty.internal.tcnative.openssl.${os.detected.name}.${os.detected.arch} 包含具体的原生二进制文件，仅在运行时需要。

在 JVM 启动参数中引入：--add-modules io.netty.tcnative.classes.openssl,io.netty.internal.tcnative.openssl.${os.detected.name}.${os.detected.arch}。

或者在 module-info.java 中显式声明：

// 添加到 module-info.java
requires io.netty.tcnative.classes.openssl;
requires io.netty.internal.tcnative.openssl.osx.aarch_64;

HTTP 压缩

Vert.x 开箱即用支持 gzip 与 deflate 压缩算法。若需要使用更高压缩比的 brotli 或 zstd 算法，你需要分别添加以下对应依赖：

  • Brotli: com.aayushatharva.brotli4j:brotli4j

  • Zstd: com.github.luben:zstd-jni

这些依赖属于可选依赖，仅在运行时生效而非编译时强制要求。

JVM 启动参数：--add-modules com.aayushatharva.brotli4j,com.github.luben.zstd_jni。

或在 module-info.java 中添加声明：

requires com.aayushatharva.brotli4j;
requires com.github.luben.zstd_jni;

代码生成 (Code Generation)

在模块化应用程序中完全支持 Vert.x 代码生成体系。

可供应用使用的模块清单如下：

Artifact ID

模块名称 (Module Name)

说明

vertx-codegen-api

io.vertx.codegen.api

Codegen 核心注解（例如 io.vertx.codegen.annotations.DataObject）

vertx-codegen-json

io.vertx.codegen.json

JSON 生成器 API（例如 io.vertx.codegen.json.JsonGen）

你的应用程序需要在 Module Path 模块路径上引入这些组件。

原 Vert.x 4 中的 vertx-codegen 组件现已细粒度拆分为：

  • vertx-codegen-processor：仅在 Java 编译器阶段必需的注解处理器；

  • vertx-codegen-api：核心契约注解；

  • vertx-codegen-json：JSON 数据转换生成器。

出于向后兼容考虑，传统的 vertx-codegen 仍然保留，开发者既可继续沿用，也可选择引入粒度更精细的独立依赖。

服务代理代码生成

为模块生成 Service Proxy 所需的最小模块声明如下：

// Service proxy 服务代理依赖声明
requires static io.vertx.codegen.api;
requires static io.vertx.codegen.json;

SQL Client Template 代码生成

生成 SQL Client Template 所需的最小模块声明：

requires static io.vertx.codegen.api;
requires io.vertx.sql.client;
requires io.vertx.sql.client.templates;

官方组件模块清单

核心组件 (Core)

Artifact ID

模块名称 (Module Name)

依赖性质

vertx-core

io.vertx.core

显式模块 (explicit)

vertx-core-logging

io.vertx.core.logging

显式模块 (explicit)
你的业务应用程序切勿显式 requires io.vertx.core.logging。该模块是 Vert.x 内部专用的日志门面抽象。应用程序应当引入你所偏好的日志实现框架（如 SLF4J、Log4j2），并配置 Vert.x 桥接使用它。

核心传递依赖

核心传递依赖均为显式模块： - Netty 库：io.netty:* - Jackson 库：com.fasterxml.jackson.core:* - Apache Log4j 2：org.apache.logging.log4j:* - SLF4J：org.slf4j:*

认证与鉴权 (Auth)

Artifact ID

模块名称 (Module Name)

依赖性质

vertx-auth-common

io.vertx.auth.common

显式模块 (explicit)

vertx-auth-htpasswd

io.vertx.auth.htpasswd

显式模块 (explicit)

vertx-auth-abac

io.vertx.auth.abac

显式模块 (explicit)

vertx-auth-ldap

io.vertx.auth.ldap

显式模块 (explicit)

vertx-auth-sqlclient

io.vertx.auth.sqlclient

显式模块 (explicit)

vertx-auth-oauth2

io.vertx.auth.oauth2

显式模块 (explicit)

vertx-auth-htdigest

io.vertx.auth.htdigest

显式模块 (explicit)

vertx-auth-jwt

io.vertx.auth.jwt

显式模块 (explicit)

vertx-auth-properties

io.vertx.auth.properties

显式模块 (explicit)

vertx-auth-webauthn4j

io.vertx.auth.webauthn4j

显式模块 (explicit)

vertx-core-otp

io.vertx.core.otp

显式模块 (explicit)

服务解析器 (Service Resolver)

Artifact ID

模块名称 (Module Name)

依赖性质

vertx-service-resolver

io.vertx.serviceresolver

显式模块 (explicit)

URI 模板 (URI Templates)

Artifact ID

模块名称 (Module Name)

依赖性质

vertx-uri-template

io.vertx.uritemplate

显式模块 (explicit)

Web 开发套件

Artifact ID

模块名称 (Module Name)

依赖性质

vertx-web-common

io.vertx.web.common

显式模块 (explicit)

vertx-web

io.vertx.web

显式模块 (explicit)

vertx-web-openapi-router

io.vertx.web.openapi-router

显式模块 (explicit)

vertx-web-validation

io.vertx.web.validation

显式模块 (explicit)

vertx-web-proxy

io.vertx.web.proxy

显式模块 (explicit)

vertx-web-graphql

io.vertx.web.graphql

自动模块 (automatic)

vertx-web-client

io.vertx.web.client

显式模块 (explicit)

vertx-web-sstore-redis

io.vertx.web.sstore.redis

显式模块 (explicit)

vertx-web-sstore-cookie

io.vertx.web.sstore.cookie

显式模块 (explicit)

vertx-web-api-service

io.vertx.web.apiservice

显式模块 (explicit)

响应式 SQL 客户端

Artifact ID

模块名称 (Module Name)

依赖性质

vertx-sql-client

io.vertx.sql.client

显式模块 (explicit)

vertx-pg-client

io.vertx.sql.client.pg

显式模块 (explicit)

vertx-mysql-client

io.vertx.sql.client.mysql

显式模块 (explicit)

vertx-mssql-client

io.vertx.sql.client.mssql

显式模块 (explicit)

vertx-oracle-client

io.vertx.sql.client.oracle

自动模块 (automatic)

vertx-jdbc-client

io.vertx.sql.client.jdbc

取决于所引入的具体 JDBC 驱动

缓存、消息与微服务组件

组件分类

Artifact ID

模块名称

依赖性质

Redis 客户端

vertx-redis-client

io.vertx.redisclient

显式模块 (explicit)

邮件客户端

vertx-mail-client

io.vertx.mail.client

显式模块 (explicit)

Cassandra 客户端

vertx-cassandra-client

io.vertx.client.cassandra

自动模块 (automatic)

Consul 客户端

vertx-consul-client

io.vertx.consul.client

显式模块 (explicit)

AMQP 客户端

vertx-amqp-client

io.vertx.amqpclient

显式模块 (explicit)

MongoDB 客户端

vertx-mongo-client

io.vertx.mongo.client

自动模块 (automatic)

STOMP 协议

vertx-stomp

io.vertx.stomp

显式模块 (explicit)

断路器 (Circuit Breaker)

vertx-circuit-breaker

io.vertx.circuitbreaker

显式模块 (explicit)

健康检查 (Health Check)

vertx-health-checks

io.vertx.healtcheck

显式模块 (explicit)

配置中心 (Config)

vertx-config

io.vertx.config

显式模块 (explicit)

JSON 校验 (Json Schema)

vertx-json-schema

io.vertx.jsonschema

显式模块 (explicit)

OpenAPI 契约路由

vertx-open-api

io.vertx.openapi

显式模块 (explicit)

MQTT 协议

vertx-mqtt

io.vertx.mqtt

显式模块 (explicit)

单元测试 (JUnit 5)

vertx-junit5

io.vertx.testing.junit5

显式模块 (explicit)

HTTP 反向代理

vertx-http-proxy

io.vertx.httpproxy

显式模块 (explicit)