主题
模块化与自动配置
一句话:Maven 负责“把哪些模块装进来”,Spring Boot 自动配置负责“装进来后怎么变成 Bean”;两者在本仓库的分工非常清楚。
1. Maven 多模块
text
pmforge(pom,version=${revision})
├── pmforge-dependencies(BOM,只管版本)
├── pmforge-framework(pom)
│ ├── pmforge-common
│ └── 14 × pmforge-spring-boot-starter-*
├── pmforge-server(jar,空壳容器)
├── pmforge-module-system
└── pmforge-module-infra
(member / bpm / report / mp / pay / mall / crm / erp /
iot / mes / wms / im 共 12 个模块已从默认注释改为全量启用)根 pom.xml 的 <modules> 现在激活 17 个一级模块(build/pmforge-bom、framework、apps/pmforge-server 与 14 个业务模块),mvn package 会构建全部 41 个 reactor 项目。启用/移除模块的步骤见模块手册。
revision 统一版本
根 pom 用 ${revision} 占位(pom.xml#L8),属性值在 #L39:
xml
<revision>2026.06-jdk8-SNAPSHOT</revision>子模块的 <parent><version>${revision}</version></parent> 都继承这个值,升级时只改一处。发布时要靠 flatten-maven-plugin 把占位符展开,否则安装/部署出去的 POM 里仍是 ${revision}:
- 插件版本
1.7.2(pom.xml#L46); flattenMode=oss(#L123)、updatePomFile=true(#L124);- profile 在
#L118-L142。
注意:pmforge-dependencies/pom.xml#L17 也声明了一份同值 revision。当前两处一致,但升级版本时必须同时改根 pom #L39 与 BOM #L17,否则 BOM 里的自研依赖会指回旧版本。
pmforge-server/pom.xml#L16-L20 自述是“空壳容器”:它不写业务,只把 module-system、module-infra 等依赖聚起来,再交给 spring-boot-maven-plugin 打成可执行 jar(#L159-L170)。
2. starter 的 core + config 约定
pmforge-framework/pom.xml#L34-L43 把约定写在了描述里:每个组件分 core 与 config 两个包;业务组件在 Maven 名里带 biz。实际目录结构:
text
pmforge-spring-boot-starter-xxx/
└── src/main/java/com/pmforge/framework/xxx/
├── core/ # 能力:工具、拦截器、枚举、抽象类
└── config/ # 装配:@AutoConfiguration + @Bean + 条件注解core 不依赖 Spring 容器也能单测;config 只做 Bean 组装,不写业务逻辑。这样同一份能力可以被不同自动配置复用,也方便在测试里只引 core。
| 模块 | 主要能力 | imports 条目数 |
|---|---|---|
starter-mybatis | MyBatis-Plus、分页、字段填充、数据源、ID 适配 | 3 |
starter-redis | Redis、缓存、Redisson | 2 |
starter-web | Web MVC、全局异常/响应、API 日志、Swagger、XSS | 7 |
starter-security | Spring Security、Token 过滤器、权限 @ss | 3 |
starter-websocket | WebSocket 会话与发送 | 1 |
starter-monitor | Tracer、Metrics | 2 |
starter-protection | 幂等、锁、限流、API 签名 | 4 |
starter-job | Quartz、@Async | 2 |
starter-mq | Redis/RabbitMQ 消息 | 3 |
starter-excel | Excel 工具 + 字典校验 | 1 |
starter-test | 测试基类与测试配置 | 0 |
starter-biz-tenant | 多租户上下文、租户拦截器 | 1 |
starter-biz-data-permission | 数据权限规则与注解 | 2 |
starter-biz-ip | IP 工具 | 0 |
starter-test、starter-biz-ip 没有 imports 入口,不代表违反约定:它们没有需要自动装配的 Bean,config 里是测试/工具配置,不是应用启动配置。
3. 两种注册方式:别把 spring.factories 当旧式自动配置
Spring Boot 2.7 同时支持两种“发现配置”的机制,但触发时机不同:
| 机制 | 读取时机 | 本仓库用途 |
|---|---|---|
META-INF/spring.factories | 应用启动早期,Environment 准备阶段 | 只注册 EnvironmentPostProcessor,在自动配置之前改配置 |
META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports | 上下文刷新、自动配置阶段 | 注册 @AutoConfiguration 类,生成业务 Bean |
imports 的实际分布(共 13 个源文件、32 个自动配置类):
text
starter-mybatis 3 DataSource / Mybatis / Translate
starter-redis 2 Redis / Cache
starter-web 7 ApiLog / Jackson / Swagger / Web / Xss / Banner / ApiEncrypt
starter-security 3 Security / WebSecurityConfigurerAdapter / OperateLog
starter-websocket 1 WebSocket
starter-monitor 2 Tracer / Metrics
starter-protection 4 Idempotent / Lock4j / RateLimiter / ApiSignature
starter-job 2 Quartz / Async
starter-mq 3 RedisMQProducer / RedisMQConsumer / RabbitMQ
starter-excel 1 Dict
starter-biz-tenant 1 Tenant
starter-biz-data-permission 2 DataPermission / DeptDataPermission
pmforge-module-iot-core 1 IotMessageBusspring.factories 只有 2 个,且都不是自动配置:
text
starter-mybatis → IdTypeEnvironmentPostProcessor
starter-biz-tenant → TenantKafkaEnvironmentPostProcessor为什么必须用 spring.factories?因为 IdTypeEnvironmentPostProcessor 要在 MyBatis-Plus 读取 mybatis-plus.global-config.db-config.id-type 之前,根据数据源类型把 NONE 改成 AUTO 或 INPUT(IdTypeEnvironmentPostProcessor.java#L24-L59),自动配置阶段再改就晚了。TenantKafkaEnvironmentPostProcessor 则把 TenantKafkaProducerInterceptor 追加到 spring.kafka.producer.properties.interceptor.classes(#L19-L31),让 Kafka 消息带上租户上下文。
所以 PM 报告里“部分老组件还在用 spring.factories 注册自动配置”的说法需要修正:本仓库没有用 spring.factories 注册任何 @AutoConfiguration,它只承载两个 EnvironmentPostProcessor。
4. 条件装配:什么时候生效
| 注解 | 真实例子 | 作用 | 注意 |
|---|---|---|---|
@ConditionalOnProperty | pmforge.tenant.enable(PmforgeTenantAutoConfiguration.java#L56)、pmforge.access-log.enable(PmforgeApiLogAutoConfiguration.java#L25)、pmforge.demo=true(PmforgeWebAutoConfiguration.java#L134-L135) | 配置开关,默认开/关由 matchIfMissing 决定 | 只能关已进 classpath 的 Bean,不能替代 pom 依赖 |
@ConditionalOnClass(name=...) | Redis/Rabbit/RocketMQ 拦截器(PmforgeTenantAutoConfiguration.java#L163、#L174、#L185);Quartz JobHandler(#L218 起) | 类存在才装配,用于可选中间件 | 字符串类名不受重构保护;类在但 Bean 缺失仍可能失败 |
@AutoConfigureOrder / before / after | Security @AutoConfigureOrder(-1)(PmforgeSecurityAutoConfiguration.java#L32-L35);MyBatis before=MybatisPlusAutoConfiguration(PmforgeMybatisAutoConfiguration.java#L34);ApiLog after=PmforgeWebAutoConfiguration(PmforgeApiLogAutoConfiguration.java#L18) | 控制自动配置之间的顺序 | 只影响自动配置,不等于 Filter 顺序 |
一个常见误区:@ConditionalOnProperty 不是“模块开关”。即使 pmforge.tenant.enable=false,starter-biz-tenant 的类仍在 classpath,只是不装配租户 Bean;要真正移除模块,必须改 pom。
5. 模块启用/停用清单
启用一个预留模块(以 member 为例),至少动五处:
| 步骤 | 文件/位置 | 动作 | 验证 |
|---|---|---|---|
| 1 | 根 pom.xml#L18-L31 | 取消对应 <module> 注释 | mvn -pl 能识别模块 |
| 2 | pmforge-server/pom.xml#L35-L137 | 取消对应依赖;mall 要加 product/promotion/trade/statistics,iot 用 iot-biz | server 能编译到模块类 |
| 3 | 依赖链 | member→pay→mall;bpm→crm;iot-core→iot-biz,按需一起放开 | 不出现 NoClassDefFoundError |
| 4 | sql/<db>/ | 默认 pmforge.sql 只有 system/infra + demo 表;预留模块的建表脚本多在 src/test/resources/sql/create_tables.sql,需先合并到主脚本 | 新库能建出模块表 |
| 5 | application-*.yaml | 按模块补配置(租户、存储、第三方密钥等) | 启动无占位符报错 |
| 6 | system_menu | 默认种子已含 system/infra 及部分预留模块菜单(支付、工作流、报表、会员等);启用前先查重,缺的补、多的下架 | 后台可见、@PreAuthorize 有权限点 |
| 7 | 构建 | 首次启用按项目文档建议 mvn -DskipTests install,再启动 server | 应用能起、接口可达 |
停用则反向执行:先下线菜单/接口流量 → 备份并保留表数据 → 去掉 server 依赖 → 注释根 pom → 清理配置。不要先删表,否则重新启用时数据不可恢复。
两个现实约束:
pmforge-ui目录在本仓库没有src/package.json,前端源码不在仓库内;菜单只能通过system_menu数据或后台接口准备。script/docs/scan-knowledge.mjs的MODULE_ORDER当前只含 system、infra;启用新模块后,生成物不会自动纳入统计,需要同步脚本。
6. 新增一个 starter 的最小步骤
- 在
pmforge-framework/下建pmforge-spring-boot-starter-xxx,parent 指向pmforge-framework。 - 按
core/config分包;config类加@AutoConfiguration,按需加条件注解。 - 在
src/main/resources/META-INF/spring/下新建org.springframework.boot.autoconfigure.AutoConfiguration.imports,一行一个配置类。 - 把模块加入
pmforge-framework/pom.xml的<modules>。 - 在消费方 pom 引依赖;版本交给 BOM,不写
<version>。 - 用
ApplicationContextRunner或现有BaseDbUnitTest验证“有条件时装配、无条件时跳过”。
7. 常见坑
- 大小写:
pmforge-framework/pom.xml#L12-L31写的是Pmforge-common、Pmforge-spring-boot-starter-*,磁盘目录是全小写。Windows 不区分大小写能解析,Linux 构建会找不到模块;应统一为小写。 - 15 个组件 ≠ 15 个 starter:framework 下是 1 个
common+ 14 个 starter。 - imports 路径必须一字不差:
META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports,放错目录不会报错,只会“Bean 莫名不存在”。 - BOM 版本两处:根
pom.xml#L39与pmforge-dependencies/pom.xml#L17。 - 注释模块仍有测试资源:
src/test/resources/sql/create_tables.sql存在,不代表生产初始化脚本已就绪。
相关页面:分层与依赖、请求处理链路、数据访问与多租户基线。