本文详细讲解如何将现有 maven 多模块项目（如 confluence 插件项目）安全、规范地合并为单模块结构，涵盖源码迁移、依赖整合、pom 调整及构建验证等关键步骤。
本文详细讲解如何将现有 maven 多模块项目（如 confluence 插件项目）安全、规范地合并为单模块结构，涵盖源码迁移、依赖整合、pom 调整及构建验证等关键步骤。
在实际开发中，尤其是中小型插件或工具类项目（例如 Confluence 关系图谱插件），过度拆分模块（如 api、impl、web、it 等）反而会增加维护成本，降低构建效率，并给 IntelliJ IDEA 的项目加载与调试带来额外复杂性。若经评估确认各子模块间无强解耦需求、不面向独立发布或复用，则合并为单模块是合理且推荐的优化手段。
✅ 合并操作步骤（Maven + IntelliJ IDEA）
1. 整理源码结构
选择一个逻辑上最适合作为“主模块”的子模块（通常是包含 main 启动入口或 atlassian-plugin.xml 的模块，如 confluence-relationship-plugin），将其 src/main/java 和 src/main/resources 内容保留；
将其他子模块（如 api、impl、web）的 src/main/java 下全部包结构合并复制至该主模块的 src/main/java 目录下（注意避免包名冲突，必要时重命名包）；
同样合并 src/main/resources（如 i18n、templates、META-INF 等资源）。
? 提示：使用 IDE 的「Refactor → Move」功能可安全迁移 Java 类并自动更新导入语句，比手动复制更可靠。
2. 统一 POM 配置
- 打开根目录 pom.xml，注释或删除
块 ：<!-- <modules> <module>api</module> <module>impl</module> <module>web</module> <module>it</module> </modules> --> - 将各子模块 pom.xml 中的关键配置提取并合并到主模块的 pom.xml 中，重点关注：
（如 confluence.version、maven.compiler.source） （去重、升级版本、检查 scope 是否合理，如 test/provided） （特别是 maven-compiler-plugin、maven-resources-plugin、Atlassian SDK 相关插件如 amps-maven-plugin） 应保持为 atlassian-plugin（Confluence 插件必需）
3. 清理冗余文件与目录
- 删除所有子模块目录（如 ./api/, ./impl/ 等）；
- 删除根目录下已失效的子模块 pom.xml；
- 若原根 pom.xml 仅作聚合用途，可将其重命名为 pom.xml.bak，并将主模块的 pom.xml 上移至项目根目录（确保路径一致）。
4. IDEA 项目重载与验证
- 在 IntelliJ IDEA 中：File → Close Project → 重新通过 Open 导入根目录下的新 pom.xml；
- IDEA 会自动识别为单模块 Maven 项目，重建 .idea/ 配置；
- 执行 Maven → Reload project，确保无红色报错；
- 终端运行：
mvn clean install -DskipTests
成功生成 target/*.jar 即表明构建通过。
⚠️ 注意事项
-
勿跳过依赖审查：子模块间可能有 compile 依赖，合并后需显式声明为
，否则编译失败； - 资源路径敏感：Confluence 插件依赖 atlassian-plugin.xml 和 Web 资源路径（如 /templates/），合并后务必验证 src/main/resources 结构是否符合 AMPs 插件规范；
- Git 提交建议：先提交合并前快照（git tag pre-merge-single-module），再执行合并，便于回溯；
- 测试策略：合并后建议运行集成测试（mvn verify）而非仅 install，确保插件在 Confluence 容器中行为不变。
完成上述步骤后，你的项目将转变为结构清晰、构建轻量、IDE 友好的单模块 Maven 工程，既保留全部功能，又显著提升开发体验与 CI/CD 效率。
