主题
pmforge-common
1. 职责
平台最底层的纯 jar:没有自动配置、没有 Bean、没有业务实现,只被其他 14 个模块依赖。它承载三类东西:跨模块契约(common.biz.* 下的 XxxCommonApi 与 DTO,让框架组件能反向调用业务能力)、统一协议(CommonResult、ErrorCode/ServiceException、分页 POJO)、通用工具与注解(Jackson 定制、脱敏、校验、缓存、WebFilterOrderEnum)。
它解决「框架组件不认识业务模块,却需要业务数据」的问题:starter-security 只声明 OAuth2TokenCommonApi,实现留在 pmforge-module-system,Maven 依赖方向始终是「框架 → 接口 ← 业务」。
它不解决:任何需要 Spring 装配的能力(Excel 在 starter-excel、字典在 starter-excel、租户在 biz-tenant);也不放业务枚举与业务表字段。
2. 关键类
| 类 | 作用 | 路径 |
|---|---|---|
CommonResult<T> | 统一返回:code/msg/data,error() 系列工厂方法 | framework/pmforge-common/src/main/java/com/pmforge/framework/common/pojo/CommonResult.java |
PageParam / PageResult / SortablePageParam | 分页入参与结果,PageResult.empty() 返回空列表 | .../common/pojo/ |
ErrorCode | 错误码接口:getCode() + getMsg() | .../common/exception/ErrorCode.java |
ServiceException / ServiceExceptionUtil | 业务异常;exception0(code, pattern, params) 用 {} 占位符格式化 | .../common/exception/util/ServiceExceptionUtil.java |
GlobalErrorCodeConstants | 系统级错误码:0 成功、400/401/403/423/429、500/501/502、900 重复请求、901 演示模式 | .../common/exception/enums/GlobalErrorCodeConstants.java |
ServiceErrorCodeRange | 10 位四段错误码区间表(只在注释里认领区间,不做运行期校验) | .../common/exception/enums/ServiceErrorCodeRange.java |
JsonUtils | 静态 ObjectMapper;init() 由 starter-web 注入 Spring 的 mapper | .../common/util/json/JsonUtils.java |
NumberSerializer / TimestampLocalDateTimeSerializer | Long 转字符串防精度丢失;LocalDateTime ↔ 毫秒时间戳 | .../common/util/json/databind/ |
CacheUtils | Guava LoadingCache:buildCache 与 buildAsyncReloadingCache(上限 10000) | .../common/util/cache/CacheUtils.java |
WebFilterOrderEnum | 全局 Filter 顺序常量(CORS=MIN、TENANT_CONTEXT=-104、API_ACCESS_LOG=-103、XSS=-102、TENANT_SECURITY=-99) | .../common/enums/WebFilterOrderEnum.java |
OAuth2TokenCommonApi / PermissionCommonApi / DictDataCommonApi / TenantCommonApi | 跨模块契约 | .../common/biz/system/*/ |
ApiAccessLogCommonApi / ApiErrorLogCommonApi / OperateLogCommonApi | 日志类契约 | .../common/biz/infra/logger/、.../common/biz/system/logger/ |
@Mobile、@Telephone、@InEnum | 通用校验注解 + Validator | .../common/validation/ |
@DesensitizeBy + *Desensitize | 字段脱敏:滑块(姓名/手机/身份证/银行卡/密码)与正则(邮箱)两套 handler | .../desensitize/core/ |
3. 自动配置
| 配置类 | 生效条件 | 注册了什么 |
|---|---|---|
| 无 | — | 本模块没有 META-INF/spring/...AutoConfiguration.imports,不注册任何 Bean |
JsonUtils#init(ObjectMapper) | 由 PmforgeJacksonAutoConfiguration 调用 | 把静态 objectMapper 换成 Spring 主 ObjectMapper |
例外是两个「静态初始化」入口,它们由别的 starter 触发:JsonUtils.init(starter-web)、DictFrameworkUtils.init(starter-excel,注入 DictDataCommonApi)。
4. 配置项
| 前缀 | 键 | 默认值 | 说明 |
|---|---|---|---|
| — | 无 | — | 本模块无 @ConfigurationProperties,也没有 application.yaml 配置项 |
5. 扩展点
- 新增跨模块契约:在
common/biz/<系统>/<领域>/放XxxCommonApi+dto/,业务模块用@Bean实现,框架组件用@ConditionalOnBean(XxxCommonApi.class)消费——PmforgeTranslateAutoConfiguration就是范例。 - 新增错误码段:先在
ServiceErrorCodeRange注释里认领区间(如1-020-000-000 ~ 1-021-000-000),再在模块内建XxxErrorCodeConstants,用ErrorCode(1_020_001_000, "…")定义。 - 自定义脱敏:实现
DesensitizationHandler并在字段上标@DesensitizeBy(handler = XxxHandler.class);内置滑块型继承AbstractSliderDesensitizationHandler。 - 自定义校验:仿照
MobileValidator写ConstraintValidator,复用ValidationUtils的正则常量。 - 替换 JSON 行为:不要在 common 里改,去 starter-web 的
Jackson2ObjectMapperBuilderCustomizer加定制。
6. 常见坑
ServiceExceptionUtil.doFormat在{}与参数数量不匹配时只打 log.error,不抛异常,消息里会残留{}或缺一段;单测请用AssertUtils.assertServiceException比对格式化后的 message,而不是比对原始模板。JsonUtils的objectMapper是静态字段:容器启动前(EnvironmentPostProcessor、静态块、@PostConstruct之前)调用它,用的是内置 mapper(NON_NULL、LocalDateTime走时间戳),与运行期 Web 层行为不一致。CacheUtils.buildAsyncReloadingCache用refreshAfterWrite+ 独立线程池异步刷新,ThreadLocal 不会过去;类注释写明「和『人』相关的缓存用buildCache」,否则会读到别的租户/登录上下文的数据。CommonResult.error(code, msg)内部有Assert.notEquals(SUCCESS.getCode(), code):把 0 当错误码传会直接抛IllegalArgumentException。- 这里虽然叫 common,但依赖并不轻:
jakarta.servlet-api(Boot 2.7 管理为 4.0.4,包名仍是javax.servlet)、springdoc-openapi-ui、easy-trans-anno都在 pom 里(注释说 easy-trans 是「方便 xxx-module-api 包使用」),所以 common 不能当成零依赖工具包拷走。
7. 关联页面
- starter-web:
JsonUtils、GlobalExceptionHandler真正生效的地方 - starter-mybatis:
BaseDO/PageResult的使用方 - starter-excel:
DictDataCommonApi、@DictFormat - 错误码段、枚举字典、横切机制