Skip to content

框架组件(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-commonpmforge-common

判断口诀:能不能在一个没有 pmforge-module-* 的空工程里跑起来。能,就是框架组件;必须靠业务模块实现某个 Api 才能工作,就是 biz 组件。starter-security 看似业务,但它只声明 OAuth2TokenCommonApi 等接口、实现留在业务模块,所以仍是框架组件。

2. 15 个组件一览 ​

模块主要能力关键自动配置类依赖(pmforge 内部)biz-
pmforge-commonPOJO、异常码、枚举、工具、脱敏、跨模块 *CommonApi 契约无(纯 jar)无(最底层)—
starter-mybatisBaseDO/BaseMapperX、分页、字段自动填充、类型处理器、多数据源、主键策略自适应PmforgeMybatisAutoConfiguration、PmforgeDataSourceAutoConfiguration、PmforgeTranslateAutoConfigurationcommon、security—
starter-redisRedisTemplate 序列化、Spring Cache、key#ttl 缓存名PmforgeRedisAutoConfiguration、PmforgeCacheAutoConfigurationcommon—
starter-web统一响应/异常、Jackson、CORS、XSS、API 加解密、访问日志、Swagger、BannerPmforgeWebAutoConfiguration 等 7 个配置类common—
starter-security登录态解析、功能权限、放行规则、操作日志PmforgeSecurityAutoConfiguration、PmforgeWebSecurityConfigurerAdapter、PmforgeOperateLogConfigurationcommon、web—
starter-websocketWebSocket 会话管理与多节点消息投递PmforgeWebSocketAutoConfigurationcommon、security、mq、biz-tenant—
starter-monitorOpenTelemetry 链路追踪、@BizTrace、Micrometer 公共标签PmforgeTracerAutoConfiguration、PmforgeMetricsAutoConfigurationcommon—
starter-protection幂等、限流、分布式锁、API 签名PmforgeIdempotentConfiguration 等 4 个web、redis—
starter-jobQuartz 调度、JobHandler 执行与重试、@Async 上下文透传PmforgeQuartzAutoConfiguration、PmforgeAsyncAutoConfigurationcommon—
starter-mqRedis Pub/Sub 与 Stream、RabbitMQ 消息转换PmforgeRedisMQProducerAutoConfiguration、PmforgeRedisMQConsumerAutoConfiguration、PmforgeRabbitMQAutoConfigurationredis—
starter-excelFastExcel 导入导出、字典翻译、Excel 下拉PmforgeDictAutoConfigurationcommon、biz-ip—
starter-test测试基座:H2、jedis-mock、Mockito、随机 POJO无(@Import 基类)common、mybatis、redis—
starter-biz-tenant多租户:SQL、缓存、MQ、Job、Swagger 全链路PmforgeTenantAutoConfigurationsecurity、mybatis、redis、job、mq✅
starter-biz-data-permission行级数据权限(部门 / 本人)PmforgeDataPermissionAutoConfiguration、PmforgeDeptDataPermissionAutoConfigurationsecurity、mybatis✅
starter-biz-ipIP 归属地、行政区划树无(纯工具类)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

三条「看不出但真实存在」的依赖,读代码前必须先知道,否则会误判分层:

  1. starter-mybatis → starter-security:mybatis 侧要用 SecurityFrameworkUtils,所以底座并不是「无依赖」的。
  2. starter-excel → starter-biz-ip:AreaConvert 用 AreaUtils 做省市区回填,框架组件反向依赖了 biz 组件。
  3. 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.enabletruefalse 时不注册 XssFilter 与 Jackson 的 XSS 反序列化器
pmforge.access-log.enabletruefalse 时不注册 ApiAccessLogFilter,访问日志不再落库
pmforge.api-encrypt.enable无默认,不写即关闭需显式 true 才注册 ApiEncryptFilter(还需配套 algorithm/request-key/response-key)
pmforge.tracer.enabletruefalse 时无 TraceFilter、无 @BizTrace 切面
pmforge.metrics.enabletruefalse 时不加 Micrometer 的 application 公共标签
pmforge.websocket.enabletruefalse 时不注册 WebSocketConfigurer,/ws 路径直接 404
pmforge.tenant.enabletruefalse 时租户拦截器、租户 Filter、租户缓存全部不装配
pmforge.demofalsetrue 时注册 DemoFilter(演示用,生产保持关闭)
springdoc.api-docs.enabledtruefalse 时 Swagger 配置类整体不生效
spring.datasource.druid.stat-view-servlet.enabledtrue(示例)true 时才注册 Druid 广告过滤(DruidAdRemoveFilter)

不在上表里的组件没有总开关:starter-mybatis、starter-redis、starter-protection、starter-job、starter-mq、starter-excel 的自动配置只要类路径命中就会生效。

6. 新增一个 starter 的步骤 ​

  1. 建 pom:framework/pmforge-spring-boot-starter-xxx/pom.xml,artifactId 用 pmforge-spring-boot-starter-xxx;含业务语义则加 biz- 前缀。记得在 framework/pom.xml 的 <modules> 里登记(注意该文件里模块名首字母大写,目录名是全小写,Linux 下大小写敏感会找不到模块)。
  2. 建包结构:com.pmforge.framework.xxx.core(能力实现)+ com.pmforge.framework.xxx.config(自动配置),每个包写 package-info.java 说明用途。
  3. 写自动配置:@AutoConfiguration + 必要的 @ConditionalOnClass / @ConditionalOnProperty,Bean 方法一律先给 @ConditionalOnMissingBean,方便业务覆盖。
  4. 注册:在 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 写全限定类名;需要改 Environment 时才用 spring.factories 的 EnvironmentPostProcessor。
  5. 写测试:src/test/java 下用 pmforge-spring-boot-starter-test 的 BaseMockitoUnitTest(纯逻辑)或 BaseDbUnitTest(要连 H2),test scope 引入即可。
  6. 登记文档:在本页表格加一行,并新建 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(幂等 / 限流 / 锁 / 签名)。

8. 关联页面 ​