高级

模块化 Vert.x 指南

从 Vert.x 5 开始，Vert.x 支持使用 Vert.x 栈构建模块化应用和服务。

本文旨在指导开发者如何使用 Vert.x 构建和运行模块化应用。

定义

我们借鉴此 文档 中的术语来定义以下名称：

  • 命名模块

  • 显式模块

  • 自动模块

成熟度模型

Vert.x 致力于提供最成熟的 JPMS 级别支持（参见 https://nipafx.dev/java-modules-jpms-maturity-model/）。

大多数 Vert.x 组件支持级别 3（根据成熟度模型）和显式模块，然而少数模块由于限制而未能实现完全的模块化，这通常是由于错误的依赖关系（例如，拆分包）造成的。

原生传输

支持原生传输。

模块 io.netty.transport.classes.${native.detected.transport} 是必需的，因为它包含传输类。

模块 io.netty.transport.${native.transport}.${os.name}.${os.detected.arch} 包含原生库，其存在仅在运行时需要。

您可以通过 JVM 启动命令 --add-modules --add-modules io.netty.transport.classes.${native.transport},io.netty.transport.${native.transport}.${os.detected.name}.${os.detected.arch} 添加它们。

或者，您也可以将它们添加到您的模块描述符中（即使您的应用程序不使用它们），这通常会触发工具在运行时自动添加它们，但这会将您的模块绑定到特定的操作系统/架构。

// Add to module-info.java
requires io.netty.transport.classes.kqueue;
requires io.netty.transport.kqueue.osx.aarch_64;

您可以在 Vert.x JPMS 示例中找到一个OpenSSL 示例。

OpenSSL

支持 OpenSSL。

模块 io.netty.tcnative.classes.openssl 是必需的，因为它包含 OpenSSL Netty 类。

模块 io.netty.internal.tcnative.openssl.${os.detected.name}.${os.detected.arch} 包含原生库，其存在仅在运行时需要。

您可以通过 JVM 启动命令 --add-modules io.netty.transport.classes.${native.transport},io.netty.transport.${native.transport}.${os.detected.name}.${os.detected.arch} 添加它们。

或者，您也可以将它们添加到您的模块描述符中（即使您的应用程序不使用它们），这通常会触发工具在运行时自动添加它们，但这会将您的模块绑定到特定的操作系统/架构。

// Add to your module-info.java
requires io.netty.tcnative.classes.openssl;
requires io.netty.internal.tcnative.openssl.osx.aarch_64;

您可以在 Vert.x JPMS 示例中找到一个OpenSSL 示例。

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 添加它们。

或者，您也可以将它们添加到您的模块描述符中（即使您的应用程序不使用它们），这通常会触发工具在运行时自动添加它们。

// Add to your module-info.java
requires com.aayushatharva.brotli4j;
requires com.github.luben.zstd_jni;

您可以在 Vert.x JPMS 示例中找到一个Brotli 示例。

代码生成

支持模块化应用的生成代码。

以下模块可用于应用程序：

Artifact ID

模块名

描述

vertx-codegen-api

io.vertx.codegen.api

代码生成注解，例如 io.vertx.codegen.annotations.DataObject

vertx-codegen-json

io.vertx.codegen.json

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

您的应用程序需要在模块路径中包含这些组件。

Vert.x 4 的 vertx-codegen 组件已拆分为：

  • vertx-codegen-processor 仅包含 Java 编译器所需的注解处理器

  • vertx-codegen-api 包含注解

  • vertx-codegen-json 包含 JSON 生成器

vertx-codegen 仍为向后兼容目的而存在，您可以随意使用它或使用更细粒度的依赖项。

服务代理生成

这是您的模块生成服务代理所需的最低要求。

// Service proxy
requires static io.vertx.codegen.api;
requires static io.vertx.codegen.json;

您可以在我们的示例集中找到服务代理示例。

SQL 客户端模板生成

待办 (需要 https://github.com/vert-x3/vertx-examples/pull/474/files)

组件

核心

Artifact ID 模块名 依赖项

vertx-core

io.vertx.core

显式

vertx-core-logging

io.vertx.core.logging

显式
您的应用程序不应直接依赖 io.vertx.core.logging，此模块包含 Vert.x 用于日志记录的抽象，并且仅供 Vert.x 组件内部使用。您的应用程序应使用您选择的日志框架并配置 Vert.x 日志以使用它。

依赖项

传递性依赖项是显式模块。

  • Netty 库 io.netty:* (参见 模块化 Netty)

  • Jackson 库 com.fasterxml.jackson.core:*

  • Apache Log4j 2 org.apache.logging.log4j:*

  • SLF4J org.slf4j:*

可选依赖项是显式模块。

  • Brotli4j com.aayushatharva.brotli4j:brotli4j

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

认证

Artifact ID 模块名 依赖项

vertx-auth-common

io.vertx.auth.common

显式

vertx-auth-htpasswd

io.vertx.auth.htpasswd

显式

vertx-auth-abac

io.vertx.auth.abac

显式

vertx-auth-ldap

io.vertx.auth.ldap

显式

vertx-auth-sqlclient

io.vertx.auth.sqlclient

显式

vertx-auth-oauth2

io.vertx.auth.oauth2

显式

vertx-auth-htdigest

io.vertx.auth.htdigest

显式

vertx-auth-jwt

io.vertx.auth.jwt

显式

vertx-auth-properties

io.vertx.auth.properties

显式

vertx-auth-webauthn4j

io.vertx.auth.webauthn4j

显式

vertx-core-otp

io.vertx.core.otp

显式

依赖项

传递性依赖项是显式模块。

服务解析器

Artifact ID

模块名

依赖项

vertx-service-resolver

io.vertx.serviceresolver

显式

URI 模板

Artifact ID

模块名

依赖项

vertx-uri-template

io.vertx.uritemplate

显式

Web

Artifact ID 模块名 依赖项

vertx-web-common

io.vertx.web.common

显式

vertx-web

io.vertx.web

显式

vertx-web-openapi-router

io.vertx.web.openapi-router

显式

vertx-web-validation

io.vertx.web.validation

显式

vertx-web-proxy

io.vertx.web.proxy

显式

vertx-web-graphql

io.vertx.web.graphql

自动

vertx-web-client

io.vertx.web.client

显式

vertx-web-sstore-redis

io.vertx.web.sstore.redis

显式

vertx-web-sstore-cookie

io.vertx.web.sstore.cookie

显式

vertx-web-api-service

io.vertx.web.apiservice

显式

vertx-web-template-mvel

io.vertx.web.template.mvel

自动

vertx-web-template-freemarker

io.vertx.web.template.freemarker

自动

vertx-web-template-thymeleaf

io.vertx.web.template.thymeleaf

自动

vertx-web-template-rocker

io.vertx.web.template.rocker

自动

vertx-web-template-handlebars

io.vertx.web.template.handlebars

自动

vertx-web-template-jte

io.vertx.web.template.jte

自动

以下模板引擎目前不支持模块化：

  • vertx-web-template-httl

  • vertx-web-template-pebble

  • vertx-web-template-pug

  • vertx-web-template-rythm

SQL 客户端

Artifact ID

模块名

依赖项

vertx-sql-client

io.vertx.sql.client

显式

vertx-pg-client

io.vertx.sql.client.pg

显式

vertx-mssql-client

io.vertx.sql.client.mssql

显式

vertx-mysql-client

io.vertx.sql.client.mysql

显式

vertx-pg-client

io.vertx.sql.client.pg

显式

vertx-oracle-client

io.vertx.sql.client.oracle

自动

vertx-jdbc-client

io.vertx.sql.client.jdbc

依赖 JDBC 库

Redis 客户端

Artifact ID

模块名

依赖项

vertx-redis-client

io.vertx.redisclient

显式

邮件客户端

Artifact ID

模块名

依赖项

vertx-mail-client

io.vertx.mail.client

显式

Cassandra 客户端

Artifact ID

模块名

依赖项

vertx-cassandra-client

io.vertx.client.cassandra

自动

Consul 客户端

Artifact ID

模块名

依赖项

vertx-consul-client

io.vertx.consul.client

显式

AMQP 客户端

Artifact ID

模块名

依赖项

vertx-amqp-client

io.vertx.amqpclient

显式

Mongo 客户端

Artifact ID

模块名

依赖项

vertx-mongo-client

io.vertx.mongo.client

自动

Stomp

Artifact ID

模块名

依赖项

vertx-stomp

io.vertx.stomp

显式

熔断器

Artifact ID

模块名

依赖项

vertx-circuit-breaker

io.vertx.circuitbreaker

显式

健康检查

Artifact ID

模块名

依赖项

vertx-health-checks

io.vertx.healtcheck

显式

配置

Artifact ID

模块名

依赖项

vertx-config

io.vertx.config

显式

vertx-config-git

io.vertx.config.git

自动

vertx-config-hocon

io.vertx.config.hocon

自动

vertx-config-configmap

io.vertx.config.configmap

显式

vertx-config-spring

io.vertx.config.spring

显式

vertx-config-yaml

io.vertx.config.yaml

显式

vertx-config-consul

io.vertx.config.consul

显式

vertx-config-redis

io.vertx.config.redis

显式

JSON Schema

Artifact ID

模块名

依赖项

vertx-json-schema

io.vertx.jsonschema

显式

Open API

Artifact ID

模块名

依赖项

vertx-open-api

io.vertx.openapi

显式

MQTT

Artifact ID

模块名

依赖项

vertx-mqtt

io.vertx.mqtt

显式

gRPC

Artifact ID

模块名

依赖项

vertx-grpc-common

io.vertx.grpc.common

自动

vertx-grpc-client

io.vertx.grpc.client

自动

vertx-grpc-server

io.vertx.grpc.server

自动

以下模块不支持模块化：

  • vertx-grpcio-common

  • vertx-grpcio-client

  • vertx-grpcio-server

从 Vert.x 5 开始，Vert.x gRPC 栈分为两部分：

  • vertx-grpc-\* 构件提供显式模块，但依赖于名为 com.google.protobuf 和 com.google.protobuf.util 的自动模块。

  • vertx-grpc-io-* 构件不能模块化，依赖于非模块化的 io.grpc:* 构件。

关于 com.google.protobuf.* 构件，在 Java Protocol Buffers 库支持模块化之前，JPMS Attic Repository 中有一个模块化版本。这里有一个模块化 gRPC 服务的示例。

JUnit 5

Artifact ID

模块名

依赖项

vertx-junit5

io.vertx.testing.junit5

显式

Vert.x 示例提供了一些使用 JUnit 5 编写的简单测试示例。

指标

Micrometer 指标

Artifact ID

模块名

依赖项

vertx-micrometer-metrics

io.vertx.metrics.micrometer

自动

Dropwizard 指标

Artifact ID

模块名

依赖项

vertx-dropwizard-metrics

io.vertx.metrics.dropwizard

自动

跟踪

Zipkin 跟踪

Artifact ID

模块名

依赖项

vertx-zipkin

io.vertx.tracing.zipkin

自动

OpenTelemetry 跟踪

Artifact ID

模块名

依赖项

vertx-opentelemetry

io.vertx.tracing.opentelemetry

自动

集群

Hazelcast 集群

Artifact ID

模块名

依赖项

vertx-hazelcast

io.vertx.clustermanager.hazelcast

显式
macOS 上模块路径不支持组播加入，需要使用 Hazelcast TCP 配置。

HTTP 代理

Artifact ID

模块名

依赖项

vertx-http-proxy

io.vertx.httpproxy

显式