使用 Maven/Gradle 构建多模块 Spring Boot 项目的最佳实践

构建大规模企业级应用通常需要模块化设计、关注点分离和高效的依赖管理。多模块 Spring Boot 项目允许将复杂系统拆分为可管理的独立模块 —— 每个模块职责明确，同时能无缝协作。

本文将带你了解使用 Maven 和 Gradle 组织多模块 Spring Boot 项目的最佳实践。

1、为什么选择多模块架构？

多模块架构 具有以下优势：

• 关注点分离：将领域逻辑、Web 接口、持久层和共享工具拆分到独立模块。
• 提升构建性能：仅需重新构建受影响的模块。
• 更优的测试与部署：支持模块独立测试和部署。
• 清晰的依赖管理：确保单向依赖关系。

2、典型模块结构

常见的多模块结构如下所示：

root-project/
│
├── api/             # DTO 和接口
├── core/            # 业务逻辑与领域（Domain）模型
├── persistence/     # 数据库访问（例如 JPA、Repository）
├── web/             # REST Controller、Spring Boot main 类
└── shared/          # 公共的工具类、枚举和异常

下图展示了模块间的依赖流向可视化表示：

• core 模块依赖 api、shared 和 persistence 模块。
• web 模块同时依赖 core 和 api 模块。
• 所有箭头向下指向，表示单向架构。

这种结构提升了复用性和清晰的层级划分：

• web 依赖 core 和 api。
• core 依赖 persistence 和 shared。
• api 与 shared 作为依赖根模块。

3、Maven 设置

根目录的 pom.xml：

<modules>
    <module>api</module>
    <module>core</module>
    <module>persistence</module>
    <module>web</module>
    <module>shared</module>
</modules>

每个模块拥有独立的 pom.xml，仅声明当前模块所需的依赖。

在根目录的 pom.xml 中使用 dependencyManagement 统一管理版本。

4、Gradle 设置

根目录的 settings.gradle.kts：

include("api", "core", "persistence", "web", "shared")

每个 build.gradle.kts 文件需应用插件并声明依赖：

dependencies {
    implementation(project(":core"))
    implementation(project(":shared"))
}

使用 version catalogs 或共享的 dependencies.gradle.kts 文件集中管理版本。

5、依赖隔离

为避免循环依赖，采用 接口驱动设计 维护模块边界：

• 在 api 模块中定义接口。
• 在 core 模块中实现接口。
• web 模块仅引用接口。

使用 Spring 的 @ComponentScan(basePackages = ...) 限制各模块的组件扫描范围。

6、运行应用

将 @SpringBootApplication Main 类置于 web 模块中，并确保所有依赖模块已在其 pom.xml 或 build.gradle.kts 中声明。

运行：

./mvnw spring-boot:run -pl web

或：

./gradlew :web:bootRun

7、最佳实践

• 🔒 避免传递依赖：每个模块需显式声明依赖。
• 📦 使用 api 和 shared 模块存放约定（即接口定义）与工具：禁止包含 Spring 相关代码。
• 🔍 通过架构规则（如 ArchUnit）强制边界。
• 🧪 隔离测试：独立单元测试各模块，仅 web 模块进行集成测试。
• 📚 记录（即文档）依赖关系 与共享 API。

8、总结

模块化 Spring Boot 应用能构建可维护、可测试且可扩展的架构。无论选择 Maven 还是 Gradle，遵循这些最佳实践可保持代码库整洁并提升团队效率。

Ref：https://www.javacodegeeks.com/2025/06/multimodule-spring-boot-projects-with-maven-gradle-best-practices.html