Vert.x 应用程序启动器 (vertx-launcher-application)

Preview

本质上，启动一个 Vert.x 应用并不是一件复杂的事情：编写一个带有 main 方法的类，初始化 Vert.x 实例并部署主 Verticle 即可。

但在工程落地中，开发者总是需要面对许多重复的基础设施诉求，例如：

动态配置 Verticle 的部署并发实例数
为主 Verticle 指定特定的 线程模型 (Threading Model)（事件循环 / Worker / 虚拟线程）
组建集群化 Vert.x 实例
接收操作系统停机信号（SIGTERM）时优雅释放 Vert.x 资源

Vert.x 应用程序启动器正是为此而生的工程开箱工具，避免在每个项目中重复编写这些样板代码。

本模块自 Vert.x 5 引入，全面取代了 Vert.x 4 时代的 io.vertx.core.Launcher。

本模块目前处于技术预览（Tech Preview）阶段，跨小版本间 API 可能会有微调演进。

引入依赖

要在项目中使用 Vert.x 应用程序启动器，请在构建描述文件中添加以下依赖：

Maven（在 pom.xml 中）：

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-launcher-application</artifactId>
  <version>5.0.12</version>
</dependency>

Gradle（在 build.gradle 文件中）：

dependencies {
  compile 'io.vertx:vertx-launcher-application:5.0.12'
}

快速上手

使用 VertxApplication 作为主类（Main-Class）启动应用：

# 假设在已配置 CLASSPATH 的 Unix 系统上运行：
java -cp $CLASSPATH io.vertx.launcher.application.VertxApplication my.app.MainVerticle

若应用被打包为可执行 Fat Jar，且在 META-INF/MANIFEST.MF 中将 Main-Class 声明为 io.vertx.launcher.application.VertxApplication，启动命令可极大简化：

java -jar myapp.jar my.app.MainVerticle

命令行参数说明

VertxApplication 主类接收的唯一位置参数就是要部署的主 Verticle 全限定类名。

若在 META-INF/MANIFEST.MF 中通过 Main-Verticle 属性预设了主 Verticle 名称，该命令行参数亦可省略：

META-INF/MANIFEST.MF 配置示例

Main-Class: io.vertx.launcher.application.VertxApplication
Main-Verticle: my.app.MainVerticle

参数配置体系

Vert.x 应用程序启动器支持高度灵活的多维配置体系：命令行参数（CLI Options）、环境变量以及系统属性（System Properties）。

命令行选项 (CLI Options)

VertxApplication 支持以下开箱即用的命令行选项：

-options, --options, -vertx-options, --vertx-options=<vertxOptionsStr>: 指定 Vert.x 核心选项。可传入 JSON 配置文件路径或内联 JSON 字符串。
-c, -cluster, --cluster: 启用集群模式。Vert.x 实例将自动与网络中的其他节点发现组网。
-cluster-port, --cluster-port=<clusterPort>: 指定集群内部通信端口，默认选用随机可用端口。
-cluster-host, --cluster-host=<clusterHost>: 指定集群内部绑定的网络接口 IP 地址。
-cluster-public-port, --cluster-public-port=<clusterPublicPort>: 指定对集群其他成员广播的公网/路由端口，默认同 cluster-port。
-cluster-public-host, --cluster-public-host=<clusterPublicHost>: 指定对集群其他成员广播的公网/路由 IP 地址，默认同 cluster-host。
-deployment-options, --deployment-options=<deploymentOptionsStr>: 指定主 Verticle 的部署选项（JSON 文件路径或内联 JSON 串）。
-w, -worker, --worker: 将主 Verticle 以工作线程（Worker）模型部署。优先级高于 deployment-options 中的声明。

环境变量配置

启动器支持通过具有特定前缀的环境变量无侵入注入配置参数。配置项名称通过去除前缀、移除下划线并转为驼峰后，自动反射匹配对应 Options 类的 Setter 方法（大小写不敏感）。

系统属性配置 (-D 参数)

支持在 JVM 启动参数中通过 -D 快速覆盖选项（如 -Dvertx.options.eventLoopPoolSize=8）。

参数覆盖优先级规则

当多项配置来源同时存在时，优先级从低到高依次为（后者覆盖前者）：

JSON 配置文件（通过 -options / -deployment-options）
操作系统环境变量
命令行参数（如 --cluster-host, --instances, --worker）
JVM 系统属性（-D）

扩展定制与钩子机制 (Hooks)

有时在环境启动前后需要执行定制动作，你可以借助钩子（Hooks）轻松注入扩展逻辑：

VertxApplicationHooks hooks = new VertxApplicationHooks() {
  @Override
  public void beforeStartingVertx(HookContext context) {
    VertxOptions vertxOptions = context.vertxOptions();
    // 在 Vert.x 启动前定制监控指标或分布式追踪配置
  }

  @Override
  public void afterVerticleDeployed(HookContext context) {
    System.out.println("主 Verticle 部署就绪！");
  }
};
VertxApplication app = new VertxApplication(args, hooks);
app.launch();

Vert.x Core

Vert.x Web