主题
基础设施模块(pmforge-module-infra)
规模:16 个 Controller、116 个接口、48 个唯一权限点、16 张表(含 5 张演示表)、234 个 Java 文件(模块目录全量,
src/main205 个)、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. 规模与口径
| 指标 | 数值 | 统计方法 |
|---|---|---|
| Controller | 16 | @RestController 类数(与 接口索引 一致) |
| 接口 | 116 | @GetMapping/@PostMapping/@PutMapping/@DeleteMapping 方法注解数 |
| 唯一权限点 | 48 | @PreAuthorize 权限标识去重 |
| 表 | 16 | 数据索引:11 张 infra_* + 5 张 pmforge_demo* |
| Java 文件 | 234 | 模块目录 Get-ChildItem -Recurse -Filter *.java |
| 功能卡 | 13 | codegen 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/download | infra_codegen_table、infra_codegen_column | INF-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-master | infra_file、infra_file_config、infra_file_content | INF-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/page | infra_job、infra_job_log | INF-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/create | infra_config、infra_data_source_config | INF-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-info | infra_api_access_log、infra_api_error_log | INF-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_grade | INF-DEMO-01、02、03 |
仓库中没有独立的「数据库文档」控制器:数据源来自
/infra/data-source-config/*,库表元数据来自/infra/codegen/db/table/list。
4. 代码生成引擎(重点)
4.1 模板类型
CodegenTemplateTypeEnum 共 6 个值,决定生成哪些文件、子表如何渲染:
| 枚举 | 值 | 含义 | 生成物差异 |
|---|---|---|---|
ONE | 1 | 单表 | 一套 CRUD + 单列表页 |
TREE | 2 | 树表 | 额外 parent_id、树形列表接口与树选择组件 |
MASTER_NORMAL | 10 | 主子表·普通 | 主表 + 子表 DO/Mapper,子表以弹窗/内嵌表格维护 |
MASTER_ERP | 11 | 主子表·ERP | 子表以可编辑明细表格维护(单据风格) |
MASTER_INNER | 12 | 主子表·内嵌 | 子表随主表一次性提交,无独立 CRUD |
SUB | 15 | 子表 | 仅作为主子表的从属,不单独建菜单 |
4.2 前端模板套数
CodegenFrontTypeEnum 有 10 个枚举值、7 套模板目录(83 个 .vm),另有 java 16 个、sql 2 个,共 101 个模板:
| 枚举值 | 模板目录 | 文件数 |
|---|---|---|
VUE2_ELEMENT_UI(10) | codegen/vue | 8 |
VUE3_ELEMENT_PLUS(20) | codegen/vue3 | 9 |
VUE3_VBEN2_ANTD_SCHEMA(30) | codegen/vue3_vben | 4 |
VUE3_VBEN5_ANTD_SCHEMA(40) / ..._GENERAL(41) | codegen/vue3_vben5_antd | 19 |
VUE3_VBEN5_ANTDV_NEXT_SCHEMA(42) / ..._GENERAL(43) | codegen/vue3_vben5_antdv_next | 19 |
VUE3_VBEN5_EP_SCHEMA(50) / ..._GENERAL(51) | codegen/vue3_vben5_ele | 19 |
VUE3_ADMIN_UNIAPP_WOT(60) | codegen/vue3_admin_uniapp | 5 |
SCHEMA 与 GENERAL 共用一套目录,靠模板内的条件分支区分「Schema 驱动的表单」与「通用表单」;scene 再分管理后台(admin)与用户 App(app,类名带 App 前缀)。
4.3 生成物结构
| 类别 | 生成路径/文件 | 说明 |
|---|---|---|
| Java | pmforge-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 落这里 |
| SQL | sql/sql.sql(业务库)、sql/h2.sql(单测) | 由 sql.vm、h2.vm 渲染 |
| 错误码 | enums/errorcode.vm 生成代码片段 | 不落独立文件,需手工合并进模块的 ErrorCodeConstants |
| 前端 | `pmforge-ui-${scene}-vue2 | vue3 |
4.4 调用链与配置
CodegenController#getTableList→DatabaseTableServiceImpl#getTableList(dataSourceConfigId, nameLike, commentLike)(MyBatis-Plus generator 的TableInfo)→ 返回可导入表。POST /infra/codegen/create-list→CodegenServiceImpl#createCodegenList逐表createCodegen,写入infra_codegen_table/infra_codegen_column。PUT /infra/codegen/sync-from-db重新读取表结构,保留用户改过的字段配置。GET /infra/codegen/preview→CodegenBuilder+CodegenEngine(Velocity)渲染为「路径 → 内容」列表。GET /infra/codegen/download打包下载;生成后仍需手工建菜单、分配权限、合并错误码。
配置前缀 pmforge.codegen:basePackage、dbSchemas、frontType、voType(VO(10)/DO(20))、deleteBatchEnable、unitTestEnable、importEnable。
5. 文件存储工厂
| 枚举 | storage | 客户端 | 配置类 |
|---|---|---|---|
DB | 1 | DBFileClient | DBFileClientConfig |
LOCAL | 10 | LocalFileClient | LocalFileClientConfig |
FTP | 11 | FtpFileClient | FtpFileClientConfig |
SFTP | 12 | SftpFileClient | SftpFileClientConfig |
S3 | 20 | S3FileClient | S3FileClientConfig |
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 管生命周期 |
任务处理器实现 JobHandler | Bean 名必须与 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 为例)
- 在
FileStorageEnum增加OSS(21, OssFileClientConfig.class, OssFileClient.class)。 - 实现
OssFileClient extends AbstractFileClient<OssFileClientConfig>(init/refresh/upload/download/delete)。 - 前端存储配置表单增加该选项;
infra_file_config的storage存 21。 - 用
GET /infra/file-config/test验证连通性,再PUT /infra/file-config/update-master切主配置。
新增一套前端代码生成模板
- 在
resources/codegen/<new-dir>/放模板(参考现有 19 个文件的 vben5 套件)。 - 增加
CodegenFrontTypeEnum值,并在CodegenEngine的FRONT_TEMPLATES表登记「枚举 → 模板 → 输出路径」。 - 补前端项目模板配置(
pmforge-ui-*的目录约定),确保生成的api/、views/路径存在。 - 用
GET /infra/codegen/preview对照现有套件检查变量与转义。
新增一个定时任务
- 写
@Component("xxxJob")实现JobHandler,返回执行结果字符串。 - 在管理后台新建任务,
handler_name填 Bean 名、cron 填 6 段表达式。 - 点「手动触发」看
infra_job_log,确认无异常后再启用。
10. 相关页面
- 接口清单:infra 接口索引
- 数据字典:infra 数据索引
- 功能卡:INF-CODEGEN-01、INF-FILE-01、INF-JOB-02
- 相邻模块:系统管理、预留模块、模块全景