主题
框架组件(15 个 Starter)
pmforge-framework 是平台的底座:15 个 Maven 模块,向上给 pmforge-module-* 与 pmforge-server 提供数据库、缓存、Web、安全、调度等能力。统一约定是 core/ 放能力实现,config/ 放 Spring 自动配置,通过 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 注册;业务模块只加依赖、加注解,不写装配代码。
1. 框架组件 vs 业务组件
划分规则写在 framework/pom.xml 的 description 里:技术组件按子包拆分,每个子包即一个组件,含 core 与 config 两个包;再按「是否含业务语义」分两类:
| 类别 | 判定依据 | Maven 命名 | 本仓库 |
|---|---|---|---|
| 框架组件 | 只依赖 Spring / 三方库,不含业务表与业务枚举;换个项目也能用 | pmforge-spring-boot-starter-* | mybatis、redis、web、security、websocket、monitor、protection、job、mq、excel、test |
| 业务组件 | 依赖平台自己的 *CommonApi 契约,或直接面向「租户 / 部门 / IP」这类业务概念 | pmforge-spring-boot-starter-biz-* | biz-tenant、biz-data-permission、biz-ip |
| 公共基础 | 两类都依赖的最底层:POJO、异常、枚举、工具、跨模块契约接口 | pmforge-common | pmforge-common |
判断口诀:能不能在一个没有 pmforge-module-* 的空工程里跑起来。能,就是框架组件;必须靠业务模块实现某个 Api 才能工作,就是 biz 组件。starter-security 看似业务,但它只声明 OAuth2TokenCommonApi 等接口、实现留在业务模块,所以仍是框架组件。
2. 15 个组件一览
| 模块 | 主要能力 | 关键自动配置类 | 依赖(pmforge 内部) | biz- |
|---|---|---|---|---|
pmforge-common | POJO、异常码、枚举、工具、脱敏、跨模块 *CommonApi 契约 | 无(纯 jar) | 无(最底层) | — |
starter-mybatis | BaseDO/BaseMapperX、分页、字段自动填充、类型处理器、多数据源、主键策略自适应 | PmforgeMybatisAutoConfiguration、PmforgeDataSourceAutoConfiguration、PmforgeTranslateAutoConfiguration | common、security | — |
starter-redis | RedisTemplate 序列化、Spring Cache、key#ttl 缓存名 | PmforgeRedisAutoConfiguration、PmforgeCacheAutoConfiguration | common | — |
starter-web | 统一响应/异常、Jackson、CORS、XSS、API 加解密、访问日志、Swagger、Banner | PmforgeWebAutoConfiguration 等 7 个配置类 | common | — |
starter-security | 登录态解析、功能权限、放行规则、操作日志 | PmforgeSecurityAutoConfiguration、PmforgeWebSecurityConfigurerAdapter、PmforgeOperateLogConfiguration | common、web | — |
starter-websocket | WebSocket 会话管理与多节点消息投递 | PmforgeWebSocketAutoConfiguration | common、security、mq、biz-tenant | — |
starter-monitor | OpenTelemetry 链路追踪、@BizTrace、Micrometer 公共标签 | PmforgeTracerAutoConfiguration、PmforgeMetricsAutoConfiguration | common | — |
starter-protection | 幂等、限流、分布式锁、API 签名 | PmforgeIdempotentConfiguration 等 4 个 | web、redis | — |
starter-job | Quartz 调度、JobHandler 执行与重试、@Async 上下文透传 | PmforgeQuartzAutoConfiguration、PmforgeAsyncAutoConfiguration | common | — |
starter-mq | Redis Pub/Sub 与 Stream、RabbitMQ 消息转换 | PmforgeRedisMQProducerAutoConfiguration、PmforgeRedisMQConsumerAutoConfiguration、PmforgeRabbitMQAutoConfiguration | redis | — |
starter-excel | FastExcel 导入导出、字典翻译、Excel 下拉 | PmforgeDictAutoConfiguration | common、biz-ip | — |
starter-test | 测试基座:H2、jedis-mock、Mockito、随机 POJO | 无(@Import 基类) | common、mybatis、redis | — |
starter-biz-tenant | 多租户:SQL、缓存、MQ、Job、Swagger 全链路 | PmforgeTenantAutoConfiguration | security、mybatis、redis、job、mq | ✅ |
starter-biz-data-permission | 行级数据权限(部门 / 本人) | PmforgeDataPermissionAutoConfiguration、PmforgeDeptDataPermissionAutoConfiguration | security、mybatis | ✅ |
starter-biz-ip | IP 归属地、行政区划树 | 无(纯工具类) | common | ✅ |
3. 依赖方向
text
pmforge-common
├─ starter-redis ── starter-mq ──┐
├─ starter-web ── starter-security ├─ starter-websocket
├─ starter-mybatis ──────────────┘
├─ starter-job / starter-monitor
└─ starter-protection(web + redis)
└─ biz-tenant / biz-data-permission / biz-ip三条「看不出但真实存在」的依赖,读代码前必须先知道,否则会误判分层:
starter-mybatis→starter-security:mybatis 侧要用SecurityFrameworkUtils,所以底座并不是「无依赖」的。starter-excel→starter-biz-ip:AreaConvert用AreaUtils做省市区回填,框架组件反向依赖了 biz 组件。starter-websocket→starter-biz-tenant:会话按租户隔离,WebSocket 因此把租户能力当成了硬依赖。
4. 自动配置是怎么被加载的
- Spring Boot 2.4+ 的入口:
src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports,一行一个全限定类名;starter-test、starter-biz-ip没有这个文件,属于「工具/基座」而非自动装配。 - Spring Boot 2 兼容入口:
META-INF/spring.factories里的EnvironmentPostProcessor,只有 mybatis(IdTypeEnvironmentPostProcessor)与 biz-tenant(TenantKafkaEnvironmentPostProcessor)使用。 - 顺序靠
@AutoConfiguration(before/after = ...)表达,例如PmforgeMybatisAutoConfiguration在 MyBatis-Plus 之前、PmforgeSwaggerAutoConfiguration在 Knife4j 之前。 - 可关开关统一走
@ConditionalOnProperty,约定前缀pmforge.<组件>.enable。
5. 全部开关速查
下面这些开关不需要改代码,在 application.yaml 里加一行就能改变装配行为(默认值取自各 @ConditionalOnProperty):
| 开关 | 默认 | 关掉 / 打开的影响 |
|---|---|---|
pmforge.xss.enable | true | false 时不注册 XssFilter 与 Jackson 的 XSS 反序列化器 |
pmforge.access-log.enable | true | false 时不注册 ApiAccessLogFilter,访问日志不再落库 |
pmforge.api-encrypt.enable | 无默认,不写即关闭 | 需显式 true 才注册 ApiEncryptFilter(还需配套 algorithm/request-key/response-key) |
pmforge.tracer.enable | true | false 时无 TraceFilter、无 @BizTrace 切面 |
pmforge.metrics.enable | true | false 时不加 Micrometer 的 application 公共标签 |
pmforge.websocket.enable | true | false 时不注册 WebSocketConfigurer,/ws 路径直接 404 |
pmforge.tenant.enable | true | false 时租户拦截器、租户 Filter、租户缓存全部不装配 |
pmforge.demo | false | true 时注册 DemoFilter(演示用,生产保持关闭) |
springdoc.api-docs.enabled | true | false 时 Swagger 配置类整体不生效 |
spring.datasource.druid.stat-view-servlet.enabled | true(示例) | true 时才注册 Druid 广告过滤(DruidAdRemoveFilter) |
不在上表里的组件没有总开关:starter-mybatis、starter-redis、starter-protection、starter-job、starter-mq、starter-excel 的自动配置只要类路径命中就会生效。
6. 新增一个 starter 的步骤
- 建 pom:
framework/pmforge-spring-boot-starter-xxx/pom.xml,artifactId用pmforge-spring-boot-starter-xxx;含业务语义则加biz-前缀。记得在framework/pom.xml的<modules>里登记(注意该文件里模块名首字母大写,目录名是全小写,Linux 下大小写敏感会找不到模块)。 - 建包结构:
com.pmforge.framework.xxx.core(能力实现)+com.pmforge.framework.xxx.config(自动配置),每个包写package-info.java说明用途。 - 写自动配置:
@AutoConfiguration+ 必要的@ConditionalOnClass/@ConditionalOnProperty,Bean 方法一律先给@ConditionalOnMissingBean,方便业务覆盖。 - 注册:在
META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports写全限定类名;需要改 Environment 时才用spring.factories的EnvironmentPostProcessor。 - 写测试:
src/test/java下用pmforge-spring-boot-starter-test的BaseMockitoUnitTest(纯逻辑)或BaseDbUnitTest(要连 H2),test scope 引入即可。 - 登记文档:在本页表格加一行,并新建
starter-xxx.md(结构见 T3 模板)。
7. 怎么读这一组页面
- 想弄清「一条请求进来会发生什么」:
starter-web(Filter 顺序)→starter-security(登录态)→biz-tenant(租户)→biz-data-permission(行级权限)。 - 想弄清「一个增删改查的底座」:
pmforge-common(契约)→starter-mybatis(DAO)→starter-redis(缓存)。 - 想接消息 / 定时 / 长连接:
starter-mq→starter-job→starter-websocket。 - 想加防护:
starter-protection(幂等 / 限流 / 锁 / 签名)。