Skip to content

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
ServiceErrorCodeRange10 位四段错误码区间表(只在注释里认领区间,不做运行期校验).../common/exception/enums/ServiceErrorCodeRange.java
JsonUtils静态 ObjectMapper;init() 由 starter-web 注入 Spring 的 mapper.../common/util/json/JsonUtils.java
NumberSerializer / TimestampLocalDateTimeSerializerLong 转字符串防精度丢失;LocalDateTime ↔ 毫秒时间戳.../common/util/json/databind/
CacheUtilsGuava 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. 常见坑 ​

  1. ServiceExceptionUtil.doFormat 在 {} 与参数数量不匹配时只打 log.error,不抛异常,消息里会残留 {} 或缺一段;单测请用 AssertUtils.assertServiceException 比对格式化后的 message,而不是比对原始模板。
  2. JsonUtils 的 objectMapper 是静态字段:容器启动前(EnvironmentPostProcessor、静态块、@PostConstruct 之前)调用它,用的是内置 mapper(NON_NULL、LocalDateTime 走时间戳),与运行期 Web 层行为不一致。
  3. CacheUtils.buildAsyncReloadingCache 用 refreshAfterWrite + 独立线程池异步刷新,ThreadLocal 不会过去;类注释写明「和『人』相关的缓存用 buildCache」,否则会读到别的租户/登录上下文的数据。
  4. CommonResult.error(code, msg) 内部有 Assert.notEquals(SUCCESS.getCode(), code):把 0 当错误码传会直接抛 IllegalArgumentException。
  5. 这里虽然叫 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. 关联页面 ​