Skip to content

模块化与自动配置 ​

一句话: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-mybatisMyBatis-Plus、分页、字段填充、数据源、ID 适配3
starter-redisRedis、缓存、Redisson2
starter-webWeb MVC、全局异常/响应、API 日志、Swagger、XSS7
starter-securitySpring Security、Token 过滤器、权限 @ss3
starter-websocketWebSocket 会话与发送1
starter-monitorTracer、Metrics2
starter-protection幂等、锁、限流、API 签名4
starter-jobQuartz、@Async2
starter-mqRedis/RabbitMQ 消息3
starter-excelExcel 工具 + 字典校验1
starter-test测试基类与测试配置0
starter-biz-tenant多租户上下文、租户拦截器1
starter-biz-data-permission数据权限规则与注解2
starter-biz-ipIP 工具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   IotMessageBus

spring.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. 条件装配:什么时候生效 ​

注解真实例子作用注意
@ConditionalOnPropertypmforge.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 / afterSecurity @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 能识别模块
2pmforge-server/pom.xml#L35-L137取消对应依赖;mall 要加 product/promotion/trade/statistics,iot 用 iot-bizserver 能编译到模块类
3依赖链member→pay→mall;bpm→crm;iot-core→iot-biz,按需一起放开不出现 NoClassDefFoundError
4sql/<db>/默认 pmforge.sql 只有 system/infra + demo 表;预留模块的建表脚本多在 src/test/resources/sql/create_tables.sql,需先合并到主脚本新库能建出模块表
5application-*.yaml按模块补配置(租户、存储、第三方密钥等)启动无占位符报错
6system_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 的最小步骤 ​

  1. 在 pmforge-framework/ 下建 pmforge-spring-boot-starter-xxx,parent 指向 pmforge-framework。
  2. 按 core / config 分包;config 类加 @AutoConfiguration,按需加条件注解。
  3. 在 src/main/resources/META-INF/spring/ 下新建 org.springframework.boot.autoconfigure.AutoConfiguration.imports,一行一个配置类。
  4. 把模块加入 pmforge-framework/pom.xml 的 <modules>。
  5. 在消费方 pom 引依赖;版本交给 BOM,不写 <version>。
  6. 用 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 存在,不代表生产初始化脚本已就绪。

相关页面:分层与依赖、请求处理链路、数据访问与多租户基线。