Skip to content

分层与依赖 ​

一句话:这个仓库是「空壳 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管理端、开放平台页面、调用方服务端权限判断
serverpmforge-server依赖聚合、启动类、application*.yaml业务 Service/Controller
modulemodule-system、module-infra用例、事务、DO/Mapper、模块内权限可被多模块复用的基础设施
frameworkcommon、starter-*通用能力、自动配置、跨模块契约具体业务表、具体业务 Service
BOMpmforge-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)在仓库中不存在。

禁止反向依赖的原因:

  1. Maven reactor 无法给环排序。A 依赖 B、B 又依赖 A,聚合构建会直接失败;即使 IDE 能跑,发布顺序也无解。
  2. framework 要能独立复用。starter 一旦依赖具体 module,就不能脱离本项目的业务模块使用,失去 starter 的意义。
  3. 模块要能选择性装配。默认只启用 system/infra;如果 framework 依赖 member,关闭 member 就会把整个应用拖垮。
  4. 变更影响面。反向依赖会让“改 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-L52SpringUtil.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. 新功能该落在哪一层 ​

按顺序问五个问题:

  1. 它有没有业务表/业务规则? 有 → module;没有 → 继续。
  2. 它会不会被两个以上模块复用? 会 → framework starter;只服务一个模块 → 留在该 module。
  3. framework 是否需要反向调用业务数据? 需要 → 在 common/biz 定义接口,实现放 module。
  4. 它只是第三方依赖的版本/聚合? 是 → BOM 或 server,不写代码。
  5. 它只是装配(扫描、开关、启动参数)? 是 → 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?
  • 关闭某个可选模块后,本功能是否仍能编译、启动、给出可读错误?

相关页面:模块化与自动配置、请求处理链路、数据访问与多租户基线。