129 lines
8.7 KiB
Plaintext
129 lines
8.7 KiB
Plaintext
================================================================================
|
||
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——任何一项都应打回
|