Skip to content

基础设施模块(pmforge-module-infra) ​

规模:16 个 Controller、116 个接口、48 个唯一权限点、16 张表(含 5 张演示表)、234 个 Java 文件(模块目录全量,src/main 205 个)、13 张功能卡。

1. 职责与边界 ​

基础设施是「开发期与运行期的工具箱」:它生成代码、存文件、跑定时任务、管配置和多数据源、记录 API 日志,并用三套示例演示代码生成器产出的三种表模型。

负责不负责
代码生成(库表导入、模板渲染、预览/下载)业务表本身的建模与字段含义(由各业务模块决定)
文件上传/下载、存储配置(本地/FTP/SFTP/S3/DB)文件归属与权限(业务侧存 URL/ID)
Quartz 定时任务、执行日志、手动触发/同步任务里的业务逻辑(由 JobHandler 实现)
参数配置、数据源配置配置项的业务语义
API 访问日志、错误日志、Redis 监控登录日志、操作日志(在 system)
单表/树表/主子表示例真实业务功能

关键事实:infra 的 pom.xml 只依赖 framework 的 10 个 starter,不依赖 system,因此它可以独立构建;代价是它不能直接调用 system 的 Service,需要跨模块能力时走 api 或事件。

2. 规模与口径 ​

指标数值统计方法
Controller16@RestController 类数(与 接口索引 一致)
接口116@GetMapping/@PostMapping/@PutMapping/@DeleteMapping 方法注解数
唯一权限点48@PreAuthorize 权限标识去重
表16数据索引:11 张 infra_* + 5 张 pmforge_demo*
Java 文件234模块目录 Get-ChildItem -Recurse -Filter *.java
功能卡13codegen 1、file 2、job 2、config/ds 2、log/redis 3、demo 3

控制器分布:代码生成 1、文件 3、定时任务 2、配置与数据源 2、日志与 Redis 3、示例 5。

3. 六个子域 ​

子域(控制器)职责代表接口(真实路径)关联表功能卡 ID
代码生成(1)导入库表元数据、编辑字段配置、预览与下载、同步表结构GET /infra/codegen/db/table/list、GET /infra/codegen/table/page、POST /infra/codegen/create-list、PUT /infra/codegen/sync-from-db、GET /infra/codegen/preview、GET /infra/codegen/downloadinfra_codegen_table、infra_codegen_columnINF-CODEGEN-01
文件存储(3)上传/预签名、文件记录、存储配置与主配置切换、按配置回读POST /infra/file/upload、GET /infra/file/presigned-url、GET /infra/file/{configId}/get/**、GET /infra/file/page、GET /infra/file-config/test、PUT /infra/file-config/update-masterinfra_file、infra_file_config、infra_file_contentINF-FILE-01、02
定时任务(2)任务 CRUD、启停、手动触发、同步 Quartz、下次执行时间、执行日志POST /infra/job/create、PUT /infra/job/update-status、PUT /infra/job/trigger、GET /infra/job/get_next_times、GET /infra/job-log/pageinfra_job、infra_job_logINF-JOB-01、02
配置与数据源(2)参数键值(带缓存)、多数据源登记与连接测试GET /infra/config/get-value-by-key、GET /infra/config/page、GET /infra/data-source-config/list、POST /infra/data-source-config/createinfra_config、infra_data_source_configINF-CONFIG-01、INF-DS-01
日志与监控(3)API 访问日志、错误日志(处理状态)、Redis 运行信息GET /infra/api-access-log/page、PUT /infra/api-error-log/update-status、GET /infra/redis/get-monitor-infoinfra_api_access_log、infra_api_error_logINF-LOG-01、02、INF-REDIS-01
示例代码(5)单表(联系人)、树表(分类)、主子表三种模式(学生/课程/成绩)/infra/demo01-contact/*、/infra/demo02-category/*、/infra/demo03-student-normal/*、-inner/*、-erp/*pmforge_demo01_contact、pmforge_demo02_category、pmforge_demo03_student、pmforge_demo03_course、pmforge_demo03_gradeINF-DEMO-01、02、03

仓库中没有独立的「数据库文档」控制器:数据源来自 /infra/data-source-config/*,库表元数据来自 /infra/codegen/db/table/list。

4. 代码生成引擎(重点) ​

4.1 模板类型 ​

CodegenTemplateTypeEnum 共 6 个值,决定生成哪些文件、子表如何渲染:

枚举值含义生成物差异
ONE1单表一套 CRUD + 单列表页
TREE2树表额外 parent_id、树形列表接口与树选择组件
MASTER_NORMAL10主子表·普通主表 + 子表 DO/Mapper,子表以弹窗/内嵌表格维护
MASTER_ERP11主子表·ERP子表以可编辑明细表格维护(单据风格)
MASTER_INNER12主子表·内嵌子表随主表一次性提交,无独立 CRUD
SUB15子表仅作为主子表的从属,不单独建菜单

4.2 前端模板套数 ​

CodegenFrontTypeEnum 有 10 个枚举值、7 套模板目录(83 个 .vm),另有 java 16 个、sql 2 个,共 101 个模板:

枚举值模板目录文件数
VUE2_ELEMENT_UI(10)codegen/vue8
VUE3_ELEMENT_PLUS(20)codegen/vue39
VUE3_VBEN2_ANTD_SCHEMA(30)codegen/vue3_vben4
VUE3_VBEN5_ANTD_SCHEMA(40) / ..._GENERAL(41)codegen/vue3_vben5_antd19
VUE3_VBEN5_ANTDV_NEXT_SCHEMA(42) / ..._GENERAL(43)codegen/vue3_vben5_antdv_next19
VUE3_VBEN5_EP_SCHEMA(50) / ..._GENERAL(51)codegen/vue3_vben5_ele19
VUE3_ADMIN_UNIAPP_WOT(60)codegen/vue3_admin_uniapp5

SCHEMA 与 GENERAL 共用一套目录,靠模板内的条件分支区分「Schema 驱动的表单」与「通用表单」;scene 再分管理后台(admin)与用户 App(app,类名带 App 前缀)。

4.3 生成物结构 ​

类别生成路径/文件说明
Javapmforge-module-${module}/pmforge-module-${module}-server/src/main/java/${basePackage}/module/${module}/...controller(含 6 个 VO:pageReq/listReq/resp/saveReq/importExcel/importResp)、dal/dataobject、dal/mysql、service、serviceImpl、test
Mapper XML...-server/src/main/resources/mapper/...联表/自定义 SQL 落这里
SQLsql/sql.sql(业务库)、sql/h2.sql(单测)由 sql.vm、h2.vm 渲染
错误码enums/errorcode.vm 生成代码片段不落独立文件,需手工合并进模块的 ErrorCodeConstants
前端`pmforge-ui-${scene}-vue2vue3

4.4 调用链与配置 ​

  1. CodegenController#getTableList → DatabaseTableServiceImpl#getTableList(dataSourceConfigId, nameLike, commentLike)(MyBatis-Plus generator 的 TableInfo)→ 返回可导入表。
  2. POST /infra/codegen/create-list → CodegenServiceImpl#createCodegenList 逐表 createCodegen,写入 infra_codegen_table/infra_codegen_column。
  3. PUT /infra/codegen/sync-from-db 重新读取表结构,保留用户改过的字段配置。
  4. GET /infra/codegen/preview → CodegenBuilder + CodegenEngine(Velocity)渲染为「路径 → 内容」列表。
  5. GET /infra/codegen/download 打包下载;生成后仍需手工建菜单、分配权限、合并错误码。

配置前缀 pmforge.codegen:basePackage、dbSchemas、frontType、voType(VO(10)/DO(20))、deleteBatchEnable、unitTestEnable、importEnable。

5. 文件存储工厂 ​

枚举storage客户端配置类
DB1DBFileClientDBFileClientConfig
LOCAL10LocalFileClientLocalFileClientConfig
FTP11FtpFileClientFtpFileClientConfig
SFTP12SftpFileClientSftpFileClientConfig
S320S3FileClientS3FileClientConfig

FileClientFactoryImpl 用一个 ConcurrentMap<Long, AbstractFileClient<?>> 按配置 ID 缓存客户端:

  • getFileClient(configId):取缓存,未命中则读 infra_file_config 并创建;
  • createOrUpdateFileClient(configId, storage, config):不存在时 ReflectUtil.newInstance(storageEnum.getClientClass(), configId, config),init() 后放入缓存;已存在则 refresh(config);
  • 新增存储类型 = 改枚举 + 写客户端/配置类 + 让工厂能实例化(反射按枚举登记,不需要改 switch)。

6. 包结构约定 ​

text
com.pmforge.module.infra
├── api/            # 对外 API(较少)
├── controller/     # admin/**(含 app/** 的 AppFileController)
├── convert/        # MapStruct
├── dal/dataobject/ # 16 个 DO
├── dal/mysql/      # Mapper
├── enums/          # FileStorageEnum、CodegenFrontTypeEnum…
├── framework/      # codegen(模板引擎)、file(客户端/工厂)、monitor、security、web
├── job/            # JobLogCleanJob、AccessLogCleanJob、ErrorLogCleanJob
├── mq/             # 消息
├── service/        # codegen、config、db、demo、file、job、logger
└── websocket/      # WebSocket 支撑
约定说明
控制器只做参数校验与 VO 转换文件、任务、代码生成的核心逻辑都在 service/framework
存储客户端实现 AbstractFileClient统一 upload/download/delete/getContent,init/refresh 管生命周期
任务处理器实现 JobHandlerBean 名必须与 infra_job.handler_name 完全一致
代码生成模板放 resources/codegen/**与 java 代码分离,便于按前端框架扩展

7. 依赖 ​

  • 仅依赖 framework starter:pmforge-spring-boot-starter-biz-tenant、-security、-websocket、-mybatis、-redis、-job、-mq、-test、-excel、-monitor。
  • 不依赖 pmforge-module-system;需要用户上下文时用 framework security 的 SecurityFrameworkUtils,需要租户时用 tenant starter。
  • 定时任务底层是 Quartz(sql/quartz.sql),与业务表分库/分 schema 部署时要注意 Quartz 表的位置。

8. 已知坑 ​

现象原因规避
导入表结构时表/注释为空元数据读的是 information_schema/pg_catalog,不同库、不同 schema 的可见性不同数据源配置里填对 dbSchemas;账号要有元数据读权限;MySQL 库名大小写敏感
任务保存成功,执行时报「找不到 handler」JobServiceImpl#updateJob 才用 SpringUtil.getBean(handlerName) 校验,createJob 只校验 cron;改名后旧记录不会自动失效Bean 名与 infra_job.handler_name 保持一致;上线前用「手动触发」验证
createJob 报 cron 非法CronUtils.isValid 校验失败,抛 JOB_CRON_EXPRESSION_VALID用 6 段 Quartz 表达式,先在 get_next_times 里验证
新增存储类型后测试通过、线上报「不支持的存储」只加了客户端,没在 FileStorageEnum 登记,或 infra_file_config.storage 仍是旧值枚举、客户端、配置类、前端字典四处一起加
代码生成后编译失败enums/errorcode.vm 只产出片段,不会合并进 ErrorCodeConstants;菜单 SQL 也未执行按生成物注释手工合并错误码,执行菜单 SQL,再改模块前缀与权限标识
生成物目录在本仓放不进去CodegenEngine 按上游多模块布局生成 pmforge-module-xxx/pmforge-module-xxx-server/... 与 pmforge-ui-${scene}-vue3/...,而本仓是扁平模块 + 单个 pmforge-ui/下载后按本仓布局移动文件、改 basePackage 与前端目录;不要直接解压覆盖
生产库出现 pmforge_demo* 表示例代码的表随主 SQL 一起初始化不需要示例时从初始化脚本移除,或单独 schema 部署

9. 扩展方式 ​

新增一种文件存储(以 OSS 为例)

  1. 在 FileStorageEnum 增加 OSS(21, OssFileClientConfig.class, OssFileClient.class)。
  2. 实现 OssFileClient extends AbstractFileClient<OssFileClientConfig>(init/refresh/upload/download/delete)。
  3. 前端存储配置表单增加该选项;infra_file_config 的 storage 存 21。
  4. 用 GET /infra/file-config/test 验证连通性,再 PUT /infra/file-config/update-master 切主配置。

新增一套前端代码生成模板

  1. 在 resources/codegen/<new-dir>/ 放模板(参考现有 19 个文件的 vben5 套件)。
  2. 增加 CodegenFrontTypeEnum 值,并在 CodegenEngine 的 FRONT_TEMPLATES 表登记「枚举 → 模板 → 输出路径」。
  3. 补前端项目模板配置(pmforge-ui-* 的目录约定),确保生成的 api/、views/ 路径存在。
  4. 用 GET /infra/codegen/preview 对照现有套件检查变量与转义。

新增一个定时任务

  1. 写 @Component("xxxJob") 实现 JobHandler,返回执行结果字符串。
  2. 在管理后台新建任务,handler_name 填 Bean 名、cron 填 6 段表达式。
  3. 点「手动触发」看 infra_job_log,确认无异常后再启用。

10. 相关页面 ​