主题
分层与依赖
一句话:这个仓库是「空壳 server + 业务模块 + 可复用 starter + BOM」的四级结构;依赖只能朝更基础的方向走,跨模块调用只走
api接口。
1. 整体分层
text
┌──────────────────────────────────────────────────────────────┐
│ client:管理端 / 开放端 / 第三方回调 │
└───────────────────────────┬──────────────────────────────────┘
│ HTTP / JSON
┌───────────────────────────▼──────────────────────────────────┐
│ server:pmforge-server(:48080) │
│ 只做依赖聚合、启动、配置;没有业务 Controller/Service │
└───────────────────────────┬──────────────────────────────────┘
│ Maven depends
┌───────────────────────────▼──────────────────────────────────┐
│ module:module-system / module-infra / 预留业务模块 │
│ Controller → Service → Mapper → DO;业务语义都在这一层 │
└───────────────────────────┬──────────────────────────────────┘
│ Maven depends
┌───────────────────────────▼──────────────────────────────────┐
│ framework:pmforge-common + 14 个 spring-boot-starter-* │
│ core 放能力,config 放自动配置;不反向依赖任何 module │
└───────────────────────────┬──────────────────────────────────┘
│ import BOM
┌───────────────────────────▼──────────────────────────────────┐
│ dependencies:pmforge-dependencies(版本唯一事实源) │
└───────────────────────────┬──────────────────────────────────┘
│ JDBC / Redis / MQ / 文件存储
┌───────────────────────────▼──────────────────────────────────┐
│ 基础设施:MySQL、PostgreSQL、Oracle、Redis、RocketMQ … │
└──────────────────────────────────────────────────────────────┘启动类只扫描 ${pmforge.info.base-package}.server 与 .module 两个包(PmforgeServerApplication.java#L14)。framework 不在 component scan 范围内,它的 Bean 全部由 AutoConfiguration.imports 装配,这也是 starter 能“即插即用”的前提。
| 层 | 代表 | 该放什么 | 不该放什么 |
|---|---|---|---|
| client | 管理端、开放平台 | 页面、调用方 | 服务端权限判断 |
| server | pmforge-server | 依赖聚合、启动类、application*.yaml | 业务 Service/Controller |
| module | module-system、module-infra | 用例、事务、DO/Mapper、模块内权限 | 可被多模块复用的基础设施 |
| framework | common、starter-* | 通用能力、自动配置、跨模块契约 | 具体业务表、具体业务 Service |
| BOM | pmforge-dependencies | 第三方与自研版本 | 业务代码、模块聚合 |
| 基础设施 | DB、Redis、MQ | 持久化与消息 | 业务规则 |
2. 依赖方向
text
业务模块(crm / erp / mes / wms / im / member / pay / report …)
│
├──────────────▶ module-system ──▶ module-infra
│ │
└───────────────────────────────────┴──▶ framework ──▶ BOM真实依赖不是“模块之间零依赖”,而是只允许单向:
module-infra只依赖 framework starter,不依赖任何 module(pmforge-module-infra/pom.xml#L21-L47)。module-system显式依赖module-infra(pmforge-module-system/pom.xml#L20-L25),并在代码里使用infra.api.config.ConfigApi(AdminUserServiceImpl.java#L15)、infra.api.websocket.WebSocketSenderApi(NoticeController.java#L8)。- 业务模块依赖更基础的模块,例如
crm依赖system、infra、bpm(pmforge-module-crm/pom.xml#L20-L35)。 - 反向依赖(infra → system、system → crm、framework → module)在仓库中不存在。
禁止反向依赖的原因:
- Maven reactor 无法给环排序。A 依赖 B、B 又依赖 A,聚合构建会直接失败;即使 IDE 能跑,发布顺序也无解。
- framework 要能独立复用。starter 一旦依赖具体 module,就不能脱离本项目的业务模块使用,失去 starter 的意义。
- 模块要能选择性装配。默认只启用 system/infra;如果 framework 依赖 member,关闭 member 就会把整个应用拖垮。
- 变更影响面。反向依赖会让“改 infra”波及“所有业务模块”,单向依赖把影响限制在下游。
跨模块协作的硬规则:只依赖对方 api 包的接口,不注入对方的 Service、Mapper、DO。接口负责契约,实现留在提供方模块,Spring 在运行期注入。
3. 依赖倒置:*CommonApi 为什么在 common
框架层需要“判断权限、校验 token、取租户”,但这些数据都在业务模块。直接依赖 module 会形成反向依赖,于是把接口下沉到 pmforge-common 的 biz 包,实现留在 module:
text
starter-security ──compile──▶ common.biz.PermissionCommonApi
▲
│ implements
module-system.PermissionApiImpl
┌─────────────────────────────┘
└── runtime:Spring 按类型注入实现(framework 不认识 module 类)pmforge-common 的 biz/package-info.java#L1-L3 写得很直白:
特殊:用于 framework 下,starter 需要调用 biz 业务模块的接口定义!
| 契约(common/biz) | 实现(module) | 谁在消费 |
|---|---|---|
PermissionCommonApi(#L10) | PermissionApiImpl(#L16-L17),PermissionApi extends PermissionCommonApi(#L13) | @ss 权限判断、PermissionServiceImpl |
OAuth2TokenCommonApi(#L14) | OAuth2TokenApiImpl(#L19-L20) | TokenAuthenticationFilter 校验访问令牌 |
TenantCommonApi(#L10) | TenantApiImpl(#L15-L16) | 租户校验、租户信息补全 |
ApiAccessLogCommonApi(#L13) | ApiAccessLogApiImpl(#L16-L18) | ApiAccessLogFilter 异步写访问日志 |
为什么不把接口放在某个 starter 里?因为契约会被多个 starter 消费(security 要权限、web 要日志、tenant 要租户),放在任一 starter 都会造成 starter 之间互相依赖;common 是所有 starter 的公共下游,放在这里没有环,坐标也稳定。
注意:common 不是“纯工具包”。它同时承担 common 工具 + biz 契约 两个职责;判断一个类该不该进 common/biz,标准是“framework 是否需要在编译期调用业务能力”,而不是“它看起来像不像通用代码”。
4. 可选模块的三种解耦手段
| 手段 | 真实落点 | 做法 | 代价 |
|---|---|---|---|
| pom 注释 | 根 pom.xml#L18-L31、pmforge-server/pom.xml#L35-L137 | 把 module 从 <modules> 和 server 依赖里注释掉(现在采用「全量启用 + demo profile」的方式,不再用注释开关) | 两处手工同步;传递依赖被隐藏;注释掉的模块没有编译校验,重新启用时容易缺依赖 |
@ConditionalOnClass(name=...) | PmforgeTenantAutoConfiguration.java#L163、#L174、#L185;Job 条件在 #L218 起 | 用字符串类名判断可选中间件是否存在,不存在就跳过整段配置 | 字符串不受 IDE 重构保护;类在但 Bean/配置不对时仍会失败;只能做“有没有”,不能做“版本是否兼容” |
SpringUtil 反射 | MemberServiceImpl.java#L47-L52 | SpringUtil.getBean(ClassUtil.loadClass(basePackage + ".module.member.api.user.MemberUserApi")),懒加载并缓存 | 启动期不校验;真正调用时才抛 ClassNotFoundException;没有编译期类型;单测要 mock 容器 |
还要区分 配置开关 和 模块解耦:@ConditionalOnProperty 只能关闭已经进入 classpath 的 Bean,不能替代 pom 依赖。例如:
pmforge.tenant.enable控制整租户能力(PmforgeTenantAutoConfiguration.java#L56);pmforge.access-log.enable控制访问日志过滤器(PmforgeApiLogAutoConfiguration.java#L25);pmforge.demo=true才注册演示过滤器(PmforgeWebAutoConfiguration.java#L134-L135)。
模块没进 classpath 时,这些开关连“关”的机会都没有。
5. 新功能该落在哪一层
按顺序问五个问题:
- 它有没有业务表/业务规则? 有 → module;没有 → 继续。
- 它会不会被两个以上模块复用? 会 → framework starter;只服务一个模块 → 留在该 module。
- framework 是否需要反向调用业务数据? 需要 → 在
common/biz定义接口,实现放 module。 - 它只是第三方依赖的版本/聚合? 是 → BOM 或 server,不写代码。
- 它只是装配(扫描、开关、启动参数)? 是 → server 配置,不新增业务类。
| 需求 | 落点 | 反例 |
|---|---|---|
| 新增“客户”CRUD、权限、菜单 | module-crm | 不要放 module-system |
| 新增一个所有模块都能用的 Excel 导出 | starter-excel | 不要复制到每个 module |
| 权限判断需要读用户角色 | common/biz 契约 + module-system 实现 | 不要让 starter 依赖 module-system |
| 升级 MySQL 驱动 | pmforge-dependencies | 不要在子 pom 写版本号 |
| 新增一个环境开关 | application-*.yaml + @ConditionalOnProperty | 不要改 Java 常量 |
6. 常见误判
- “server 是业务入口”:server 是空壳容器,业务入口在 module 的 Controller。
- “模块可以互相随便调”:只允许朝基础模块单向依赖;跨模块调用只走
api接口。 - “framework 的 Bean 会被扫描到”:启动类只扫 server/module,framework 靠自动配置注册。
- “15 个 starter”:framework 下是 1 个
common+ 14 个 starter,共 15 个 Maven 模块。 - “pom 注释等于模块没依赖”:注释只影响本 reactor 的装配,传递依赖和 SQL/菜单仍需人工核对。
7. 落地检查清单
- 新类所在包是否能从 module/framework/server 三层中唯一归属?
- 是否新增了
module → 业务模块的反向依赖? - 跨模块调用是否只碰对方
api包? - framework 需要业务能力时,契约是否放在
common/biz? - 关闭某个可选模块后,本功能是否仍能编译、启动、给出可读错误?
相关页面:模块化与自动配置、请求处理链路、数据访问与多租户基线。