在公司级后端项目中，Maven 多模块往往成为“乱象”的代名词。一次简单的版本升级，几乎会导致整个程序出现运行时错误；新功能的实现常常被循环依赖卡住；甚至每次新增模块都像是在拼装乐高，难度极大。下面内容将方便你梳理并解决这些痛点。

多模块工程的典型痛点

1️⃣ 版本号地狱

你在使用者模块引入了 sa-token@1.x。消息模块引入了同一库的1.y，流程模块又用了1.z。三者同时存在于 classpath 中，偶尔就会抛出 NoSuchMethodError。更糟的是导致版本不一致，

2️⃣ 循环依赖困扰

A 模块依赖 B，B 再依赖 C。不过，某天 C 的新功能需要调用 A 的接口。却触发 Maven 的 “cyclic reference” 错误。你只能抽取公共代码到一个新模块，接下来再重新组织依赖——这一步耗时至少一周。

3️⃣ 难以追踪改动影响

根 POM 用 升级了某第三方库的 patch 版，却没意识到它被哪些子模块间接引用。怎么说呢，两周后生产环境出现奇怪 bug。你花两天排查才发现是该库序列化行为被修改。

4️⃣ 新增模块成本高昂

需求变更让你必须添加一个新的 Maven 模块，你得决定父 POM、版本号位置、依赖关系还有可能产生的循环。若答复不清晰，新模块要么耦合过深，要么孤立无援。

Forge Admin 的干净多层架构

主要原则：所有依赖方向从上向下单向流动，永不反向。

┌─────────────────┐
│ forge │ ← 统一版本号、全局插件
└────────┬────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
│ forge-admin- │ │ forge- │ │ forge-report/ │
│ server │ │ framework/ │ │ │
└─────────────────┘ └──────┬───────┘ └─────────────────┘
▲ ▲
┌───────────────────────┼───────────────────────┐
▼ ▼ ▼
┌─────────────────────┐ ┌───────────────┐ ...
│ forge-dependencies │ │ starter-parent│
| | | |
+---------------------+ +---------------+

BOM统一管理所有第三方和内部组件的版本，从而消除“多版本冲突”。

主要机制这方面，BOM统一版本管理

① 导入外部 BOM

在 org.springframework.boot spring-boot-dependencies pom import ...

② 覆盖特定第三方库的版本

cn.dev33
sa-token-spring-boot3-starter


...

com.mdframe.forge
forge-starter-core
${revision}

...

③ 子模块如何声明依赖？

最简 Starter 示例:

com.mdframe.forge
forge-starter-parent



com.mdframe.forge
forge-starter-core

 

com.baomidou
tag...


④ 主应用入口示例：



/.../plugin-system...
...
/.../starter-web...
...

...




只需修改forge-dependencies/pom.xml中的一个字段，即可影响所有子项目。


关键取舍与踩坑技巧 



**为什么不把所有子模块平铺在根 POM 下？**
- **逻辑分组**：Starter 与 Plugin 一目了然
- **独立建立**：可针对框架层单独打包
- **隔离风险**：Plugin 不会意外拉入应用层代码

**为何将 forge-dependencies 单独成模？说起来，**
- 可复用给其他项目
- 根 POM 专注插件与聚合
- 单独发布便于维护

**optional=true 的哲学**
- 如租户插件对 ORM 标记为 optional。可让非 ORM 项目免受 MyBatis 拉拽。### 常见踩坑一览


问题
原因
方法 


1️⃣  NoSuchMethodError
手写版号导致冲突
删掉手写版号。让 BOM 管理 

2️⃣  循环依赖
A→B→C→A
提炼公共接口到上一层或拆分成独立 Starter 

3️⃣  传递过多
某插件拉进不需要的 Starter
加 optional 或拆分为独立子包 

4️⃣ 建立慢
每次都全量编译
使用 `mvn clean install -pl target-module -am` 指定目标子项目 

5️⃣ 新增模失联
忘记更新 `` 列表
确保 `forge-starter-parent/pom.xml` 和 `plugin-parent/pom.xml` 中已声明新 module 



二开教程的观点是，快速新增一个技术 Starter 模块 


① 确认归属层级 → 放置于 `forge-framework/forge-starter-parent/` 下。

② 在 `forge-dependencies/pom.xml` 中注册 `` 并使用 `${revision}`。其实，

③ 在 `forge-starter-parent/pom.xml` `` 声明 ``。

④ 创建目录及 POM，并继承父 POM；内部引用仅使用 `forge-starter-core`；外部 SDK 在 BOM 管理中引用。

⑤ 如需要可在 `forge-admin-server/pom.xml` 引入此 starter。









体验入口与下一篇预告 


# 在线演示：www.dlforgelab.com:/forge/login

# 源码托管：Gitee gitee.com/ForgeLab/fo…| GitHub github.com/yaomindong1…

# 快速建立示例



# 建立框架层
$ cd forge && mvn clean install -pl forge-framework -DskipTests

# 建立仅 Starter 层
$ cd forge && mvn clean install -pl forge-framework/forge-starter-parent -am -DskipTests

# 全项目建立
$ cd forge && mvn clean install -DskipTests=true..?$ cd forge && mvn clean install -DskipTests=true\t






# 下一篇预告：A04｜统一响应、异常处理和日志 —— 拆解 `forge-starter-core`,`forge-starter-web`。和 `GlobalExceptionHandler`.
The above provides a complete HTML-formatted guide that directly addresses common Maven multi-module pain points while preserving original technical details..