本文详解如何基于 gradle 构建符合企业级规范的 quarkus 多模块项目，通过根项目统一管理依赖与构建配置，子模块（如 api、ui、cashflow）按职责分离，并支持静态资源（views）与传统 web-inf/lib 目录结构的兼容性集成。
本文详解如何基于 gradle 构建符合企业级规范的 quarkus 多模块项目，通过根项目统一管理依赖与构建配置，子模块（如 api、ui、cashflow）按职责分离，并支持静态资源（views）与传统 web-inf/lib 目录结构的兼容性集成。
要成功搭建一个结构清晰、可维护性强的 Quarkus 多模块 Gradle 项目，关键在于合理设计项目层级与依赖关系。以下为完整实践指南：
✅ 1. 初始化根项目结构
首先，在项目根目录（root-folders）创建标准 Gradle 项目骨架，并确保包含以下核心文件：
- settings.gradle（必需）：声明所有子模块
- build.gradle（根构建脚本）：定义全局插件、仓库、依赖版本及公共配置
- gradle.properties（可选）：集中管理版本号（如 quarkusVersion=3.15.0）
示例 settings.gradle：
rootProject.name = 'quarkus-parent' include 'api', 'ui', 'cashflow', 'views' // 注意：WEB-INF 不作为独立模块（非 Gradle 模块），而是作为 ui 或 web 模块的资源目录
⚠️ 注意：WEB-INF/lib 是传统 WAR 部署结构，而 Quarkus 默认构建为可执行 JAR（不依赖 WEB-INF）。若需兼容 Servlet 容器部署（如 Tomcat），应启用 quarkus-undertow 并配置 quarkus.package.type=legacy-jar，再通过自定义 copyLibs 任务将依赖 JAR 复制到 WEB-INF/lib。
✅ 2. 子模块职责划分与依赖管理
各子模块应为独立的 Gradle 子项目（即各自含 build.gradle），并遵循分层依赖原则：
- api：定义共享 DTO、REST 接口契约（@Path, @GET 等），不依赖其他业务模块
- cashflow：实现核心领域逻辑，依赖 api
- ui：提供 Web 层（如 REST 控制器 + Thymeleaf/HTML 渲染），依赖 api 和 cashflow
- views：纯静态资源模块（HTML/CSS/JS），建议设为 java-library 类型，供 ui 通过 implementation project(':views') 引入资源路径
示例 ui/build.gradle 片段：
dependencies {
implementation project(':api')
implementation project(':cashflow')
implementation project(':views') // 提供静态资源
implementation 'io.quarkus:quarkus-resteasy-reactive'
implementation 'io.quarkus:quarkus-qute'
}✅ 3. 统一依赖与版本控制（推荐方式）
在根 build.gradle 中使用 platform + enforced-platform 实现依赖收敛：
plugins {
id 'io.quarkus' version "${quarkusVersion}"' apply false
}
dependencyManagement {
imports {
mavenBom "io.quarkus:quarkus-bom:${quarkusVersion}"
}
}所有子模块只需声明功能依赖（无需指定版本），由 BOM 自动对齐：
// api/build.gradle
dependencies {
implementation 'io.quarkus:quarkus-resteasy-reactive-jsonb' // 版本由 BOM 决定
}✅ 4. WEB-INF/lib 的兼容性处理（如需 WAR 部署）
Quarkus 默认不生成 WEB-INF，但可通过以下方式支持：
-
启用传统打包类型：
// 在 ui/build.gradle 中 quarkus { package { type = 'legacy-jar' // 生成可部署到 Servlet 容器的 JAR/WAR } } -
添加自定义任务复制依赖至 WEB-INF/lib：
// ui/build.gradle task copyLibsToWebInf(type: Copy) { from configurations.runtimeClasspath into file("$project.buildDir/classes/java/main/WEB-INF/lib") } classes.finalizedBy copyLibsToWebInf
? 提示：现代 Quarkus 应用更推荐原生镜像或可执行 JAR 部署；仅当遗留系统集成必需时才启用 legacy-jar 模式。
✅ 总结
- ✅ 使用 settings.gradle 声明模块关系是多模块项目的基石
- ✅ 依赖应单向流动（子模块 → 父模块 / 基础模块 → 业务模块），避免循环依赖
- ✅ Quarkus 的 BOM 机制 + 根项目统一配置，显著提升可维护性
- ⚠️ WEB-INF/lib 属于历史兼容方案，新项目建议拥抱 Quarkus 原生运行时模型
通过以上结构，您将获得一个清晰、可扩展、符合 Quarkus 最佳实践的多模块工程体系。
