================================================================================ EasyGoAdmin 后端开发者文档 · 18 扩展开发与变更管理 ================================================================================ 按“变更类型”给出标准操作清单（checklist），保证不漏步骤、不变异架构。 -------------------------------------------------------------------------------- 1. 给现有模块新增一个接口 -------------------------------------------------------------------------------- □ api/v1/{模块}.go：新增 {Mod}{Action}Req（内嵌 gmeta.Meta，path 带 /api 前缀、 permission、log、logType）+ {Mod}{Action}Res □ controller：同名方法，签名 func (c *CXxx) Action(ctx, req) (res, err) □ service/{模块}.go：接口追加方法声明（手维护） □ logic：实现方法（基座可表达走 spec 钩子，复杂走手写） □ 权限节点同步：若 permission 为新码，需在菜单管理为角色勾选 （或插入 goframe_menu type=1 节点） □ go build ./... && gofmt；重启；/api.json 核对新条目 □ 变更回归（16 章第 6 节对应行） -------------------------------------------------------------------------------- 2. 给现有模块加字段 -------------------------------------------------------------------------------- □ MySQL ALTER（列注释按枚举规范写“字段：1-x 2-y”；需要唯一性则补 uk_*） □ gf gen dao -c hack/config.yaml（刷新 entity/do/dao internal；service 不动） □ api/v1：Req/Res/Item 结构体补字段（json 驼峰 + dc 注释） □ logic：ToData 补键；如为枚举补 SerializeMaps（字典编码 {模块}_{字段}）； 文件字段补 FileFields+FileSaveDir；富文本补 ContentFields □ 前端：columns.ts / querySchemas.ts / edit.vue 同步（生成器模块可 -preview 对照模板手改） □ resource/sql 五份方言 DDL 同步；必要时 12 章清单更新 □ go build → 重启 → page/detail 黄金样本更新 -------------------------------------------------------------------------------- 3. 新增模块 -------------------------------------------------------------------------------- □ 设计表（统一审计列 + del_flag + uk_* + 注释枚举）→ DDL 落库 □ 租户级？→ hooks.tenantTables 登记（12 章第 6 节） □ go run ./cmd/generator -tables "goframe_x|中文名"（或手动四件套） □ logic 调整：spec 声明（筛选/树形/字典/文件/唯一 Group）、扩展接口 □ service 接口核对（生成器已产出，按需扩展）；router.go 注册行确认 □ go build ./... → 重启 → 角色勾选新权限节点 □ 00 章模块表、11 章接口清单、12 章表清单同步更新（文档纪律） -------------------------------------------------------------------------------- 4. 新增中间件 -------------------------------------------------------------------------------- □ internal/middleware/{name}.go：func(r *ghttp.Request)，职责单一； 读配置用 cfgBool/cfgInt；客户端 IP 用 realClientIP；响应用 utility/response □ 不得 import 业务包——需要业务数据时在 wire.go 增加 Loader 函数变量， 由 logic init 注册（参照 IdentityLoader 模式） □ router.Register 的 s.Use 链按序插入（顺序即语义，评审明确插入点） □ public 路径行为：确认对 IsPublicPath 的放行策略 □ 02 章与 00 章链路描述同步更新 -------------------------------------------------------------------------------- 5. 新增定时任务 -------------------------------------------------------------------------------- □ internal/task/{task_name}.go + init RegisterJobHandler("TaskName", h) □ handler 签名 (ctx, params) (string, error)；长任务分批+上限；禁 HTTP 于 事务内；可复用 base（WithTrans/ChunkQuery） □ 任务表配置：url="TaskName"、params JSON、cron（6 段或 # 5 段）、 execute_policy/is_sync；发布（status=1） □ 验证：daemonStatus 挂载 + runOnce + job/log 成功记录 □ go build 重启（init 注册发生在进程加载期） -------------------------------------------------------------------------------- 6. 自定义 / 扩展 dao -------------------------------------------------------------------------------- □ 生成的 dao/{m}.go（自定义模板 hack/tpl/dao_index.tpl 产物）可安全手改： 挂钩子 + Ctx 覆写已在生成模板内；在文件尾部“Add your custom methods” 区追加方法（如统计/联查），保持只依赖 dao 内部与 gdb □ 修改模板本身：改 hack/tpl/dao_index.tpl 后 gf gen dao 重新生成全部 （overwriteDao:false 保留手工扩展文件——注意新旧模板产物差异需人工合并） □ 红线：自定义方法也必须以 Ctx(ctx) 为查询入口（否则丢失租户/软删过滤）； 禁止在 dao 内做业务判断 -------------------------------------------------------------------------------- 7. 逃生舱与扩展挂点 -------------------------------------------------------------------------------- BodyUnmarshaler 请求体形态不规则（平铺 map 等）时，Req 实现 UnmarshalBody(r) 跳过默认 Parse（自行做 gvalid） ModuleSpec.Filter 复杂查询条件（不与 Like/Eq 重复） ModuleSpec.DataScope 数据权限挂点（已接通）：共享工厂 ApplyDataScope(col) 位于 logic/data_scope.go；模块声明 DataScope 即生效， 作用于 Page/List/导出；档位见 17 章授权安全细节 ModuleSpec 钩子写不进 基座禁止按模块分支——写不进钩子就整个方法手写 （合法逃生舱，如 job.Detail 因嵌入结构手写） logic 包级共享函数 跨模块复用放具体模块文件顶部（同包可见）； 横切能力进 base.go（导出上限 15 个，超出拆子包） RegisterJobHandler 本地任务处理器全局注册表（重名 panic） middleware wire 三 Loader/Sink 函数变量，业务与中间件解耦 -------------------------------------------------------------------------------- 8. 配置变更 -------------------------------------------------------------------------------- □ manifest/config/config.yaml 修改（键义见 10 章） □ 多环境差异用 GF_GENV_ 环境变量覆盖（如 GF_GENV_DATABASE_DEFAULT_LINK）， 不改文件 □ 新增配置键：config.yaml 注释说明 + 代码 cfgBool/cfgInt 带默认值读取 （缺失不 panic）+ 10 章文档同步 □ 影响限流/日志/上传/调度的键变更后跑对应回归（16 章第 6 节） -------------------------------------------------------------------------------- 9. 未启用项与前端遗留 -------------------------------------------------------------------------------- 项 现状 启用/处理要点 ---------------- --------------------------------------- ----------------- 用户注册 publicPaths 含 /api/register 启用时补建表逻辑+ （路由未注册） 开放策略+租户归属规则 数据范围自定义档 现四档纯列值（role.data_scope） 第5档+部门关联表+ 角色表单部门树多选 导出增强 当前导出返回临时文件 URL 可加流式下载/异步导出 SendSms 任务 task/send_sms.go 仅记日志 接短信通道时替换实现 站内信/数据源 前端废弃功能（sendMsg.vue、 后端不实现；前端调用 dataSource.ts） 点为遗留死代码 短信/OSS/WebSocket 后端桩接口已删除 前端遗留调用为废弃代码， 不再调用即无影响 注：角色数据权限（四档）已实现，见 17 章授权安全细节与 logic/data_scope.go。 -------------------------------------------------------------------------------- 10. 封板后的变更纪律 -------------------------------------------------------------------------------- 1) 一切接口行为以 11 章清单 + /api.json 为准，改动即更新文档 2) 表结构改动三同步：MySQL 定稿 → resource/sql 四方言 → 迁移（如跨环境） 3) 破坏性变更（改名/删字段/改枚举值）必须走版本化说明 + 前端同步 + 黄金 样本更新，禁止静默变更 4) 架构红线复查：绕过 dao/手写租户条件/反向依赖 task/超 15 导出的 base/ 未登记 tenantTables——任何一项都应打回