267 lines
16 KiB
Plaintext
267 lines
16 KiB
Plaintext
================================================================================
|
||
EasyGoAdmin 后端开发者文档 · 04 模块开发规范与 CRUD 基座
|
||
================================================================================
|
||
代码位置：api/v1/{模块}.go、internal/controller/{模块}.go、
|
||
internal/logic/{模块}.go、internal/service/{模块}.go、
|
||
internal/logic/module_spec.go（ModuleSpec 基座）
|
||
|
||
--------------------------------------------------------------------------------
|
||
1. 新增模块四件套（平铺放置，同包 init 自动注册）
|
||
--------------------------------------------------------------------------------
|
||
api/v1/{模块}.go 全部 Req/Res 结构体 + gmeta 注解（单包 v1）
|
||
internal/controller/{模块}.go 控制器 CXxx，方法签名统一：
|
||
func (c *CXxx) Page(ctx, req *v1.XxxReq) (*v1.XxxRes, error)
|
||
internal/logic/{模块}.go 业务实现 sXxx + var xxxSpec = ModuleSpec[...]{...}
|
||
+ init(){ service.RegisterXxx(&sXxx{}) }
|
||
internal/service/{模块}.go 手维护接口 IXxx + RegisterXxx + 取用函数 Xxx()
|
||
路由：router.go registerControllers 追加 Bind(s, new(controller.CXxx))
|
||
（生成器自动写入；手动新增则自行追加在最后一个 Bind 行后）
|
||
dao 四件（dao/{m}.go、dao/internal/{m}.go、entity、do）由 gf gen dao 或
|
||
生成器产出。
|
||
|
||
文件命名：表名去 goframe_ 前缀的 snake_case（config_item.go / file_template.go）；
|
||
前端文件仍用驼峰（fileTemplate.ts）。
|
||
|
||
--------------------------------------------------------------------------------
|
||
2. 标准七件套 + 扩展
|
||
--------------------------------------------------------------------------------
|
||
方法 HTTP 路由模板 说明
|
||
Page GET /api/{prefix}/page 分页（pageNo/pageSize + 筛选）
|
||
List GET /api/{prefix}/list 全量/树形（下拉、树选择）
|
||
Detail GET /api/{prefix}/detail/:id 详情
|
||
Add POST /api/{prefix}/add 新增，返回 {id}
|
||
Update PUT /api/{prefix}/update 修改（body 含 id）
|
||
Delete DELETE /api/{prefix}/delete/:id 软删（del_flag=1）
|
||
BatchDelete DELETE /api/{prefix}/batchDelete body {ids:[]}
|
||
Import POST /api/{prefix}/import multipart file（xls/xlsx）
|
||
Export GET /api/{prefix}/export 导出文件
|
||
Status PUT /api/{prefix}/status 状态切换（有 status 列的模块）
|
||
|
||
命名约定：结构体 {Mod}{Action}Req / {Mod}{Action}Res；controller 方法名 =
|
||
logic 方法名 = 上表方法名。日志标题 "{模块中文名}-{动作}"，动作映射：
|
||
page=查询分页记录 list=查询列表（树形=查询树形列表） detail=查询详情
|
||
add=新增记录 update=修改记录 delete=删除记录 batchDelete=批量删除记录
|
||
import=导入数据 export=导出数据 status=设置状态 reset=重置。
|
||
|
||
--------------------------------------------------------------------------------
|
||
3. gmeta 注解完整示例
|
||
--------------------------------------------------------------------------------
|
||
type UserPageReq struct {
|
||
gmeta.Meta `method:"get" path:"/api/user/page" summary:"用户分页"
|
||
permission:"sys:user:page" log:"用户管理-查询分页记录" logType:"query"`
|
||
common.PageReq
|
||
Keyword string `json:"keyword" dc:"关键词"`
|
||
Status int `json:"status" dc:"状态"`
|
||
}
|
||
|
||
* permission 空 = 登录即可（如 /api/index/*、/api/job/daemonStatus、
|
||
字典别名 /api/dictionary/* 等）
|
||
* public:"true" 仅用于免登录路由，且必须同时出现在 middleware/public.go
|
||
* 入参 json 一律驼峰；路由参数 :id 由 gmeta path 声明、req 结构同名字段承接
|
||
|
||
--------------------------------------------------------------------------------
|
||
4. ModuleSpec 声明式 CRUD 基座（module_spec.go）
|
||
--------------------------------------------------------------------------------
|
||
泛型 ModuleSpec[Item, LItem, DRes]：
|
||
Item 分页行类型（Page/AfterPageList）
|
||
LItem 列表行类型（List/树形，可与 Item 相同）
|
||
DRes 详情类型
|
||
|
||
设计纪律：
|
||
1) 基座禁止“按模块分支”——差异只进声明字段与钩子；写不进钩子 → 手写（合法逃生舱）
|
||
2) 钩子用具体函数类型；req any 经 mustAs[T] 断言（失败=编程错误，panic）
|
||
3) 钩子内可改元素/data，禁止 append、禁止 HTTP/文件 IO（文件迁移统一在 saveTransform）
|
||
4) applyFilters 固定顺序：LikeFields → EqFields → KeywordFields → Filter → DataScope；
|
||
租户/软删隔离由 dao.Ctx 先于本链注入
|
||
5) ToData：Add=全量必填；Update=全量表单语义（前端 Detail 回显 → 全量 PUT）
|
||
6) 钩子错误记 stage 日志后原样上抛（保留 gerror 语义码）
|
||
|
||
4.1 声明字段
|
||
Model func(ctx) *gdb.Model 数据源（通常 dao.Xxx.Ctx）
|
||
LikeFields []string 逐列 LIKE（值取 req 同名驼峰字段，空跳过）
|
||
EqFields []string 等值（零值跳过）
|
||
KeywordFields []string req.keyword 多列 OR（能力保留在基座，
|
||
模块默认不声明，需要时再用）
|
||
Filter func(ctx, m, req) *gdb.Model 复杂条件逃生舱
|
||
OrderBy 默认排序（如 "id DESC"）；ListOrderBy 列表排序；
|
||
OrderableFields 前端排序白名单（orderField/orderType 仅白名单内生效）
|
||
IsTree/ParentOf/ChildSetter 树形（List 末尾建树；缺 ParentOf fail-fast）
|
||
SerializeMaps map[字段]字典编码 {field}Text 填充
|
||
FileFields / MultiFileFields / ContentFields /
|
||
FileSaveDir 文件/富文本声明（写侧转正、读侧补 URL/还原占位符，见 05 章）
|
||
FieldLabels 唯一校验提示覆盖
|
||
UniqueFields []UniqueRule{Field, Group} 唯一性预检（Group 支持分组唯一，
|
||
如 Group:"tenant_id"）
|
||
DataScope 行级数据权限（共享工厂 ApplyDataScope(deptColumn)，
|
||
logic/data_scope.go；nil 跳过；仅 Page/List/导出生效；
|
||
模块一行声明即接线，机制见 03 章第 6 节，安全边界见 17 章）
|
||
钩子 BeforeAdd/AfterAdd/BeforeUpdate/AfterUpdate/BeforeDelete/
|
||
AfterDelete/BeforeBatchDelete/AfterBatchDelete/
|
||
AfterPageList（禁 append）/AfterDetail
|
||
ToData req → map[string]any（新增/修改共用转换）
|
||
|
||
4.2 基座流水线
|
||
Page applyFilters → Count → applyOrder.Page → structRows → readTransform
|
||
→ AfterPageList
|
||
List applyFilters → 排序 → req.limit 上限 → structRows → readTransform
|
||
→ IsTree 时 buildTree（叶子 Children 预置 [] 而非 null）
|
||
Detail Model.Where(id).One → Struct → readTransform → AfterDetail
|
||
Add ToData → BeforeAdd → saveTransform（文件/富文本转正）→ checkUniqueRules
|
||
→ Insert → LastInsertId → AfterAdd → 返回 id
|
||
Update ToData → BeforeUpdate → saveTransform → checkUniqueRules(排除自身)
|
||
→ Update（仅更新 data 中出现的键）→ AfterUpdate
|
||
Delete BeforeDelete → Delete（钩子改写软删）→ AfterDelete
|
||
BatchDelete BeforeBatchDelete → 逐条 BeforeDelete+软删 → AfterBatchDelete
|
||
MergeOld(data, id)：把 data 中缺失/零值键用库中旧值补齐（全量覆盖辅助）
|
||
|
||
4.3 标准模块声明示例（节选自 job 模块）
|
||
var jobSpec = ModuleSpec[v1.JobItem, v1.JobItem, v1.JobDetailRes]{
|
||
Model: dao.Job.Ctx,
|
||
LikeFields: []string{"job_name", "job_alias"},
|
||
EqFields: []string{"status"},
|
||
OrderBy: "id DESC",
|
||
SerializeMaps: map[string]string{"status": "job_status", ...},
|
||
ToData: jobToData,
|
||
BeforeAdd: jobDefaultStatus,
|
||
BeforeUpdate: jobExistGuard,
|
||
AfterUpdate: jobRemount,
|
||
BeforeDelete: jobDeleteGuard,
|
||
}
|
||
业务方法三行委托：
|
||
func (s *sJob) Page(ctx, req) (*v1.JobPageRes, error) {
|
||
list, total, err := jobSpec.Page(ctx, req, req.GetPageNo(), req.GetPageSize())
|
||
...
|
||
return v1.NewPageData(..., derefSlice(list)), nil
|
||
}
|
||
|
||
4.4 唯一校验语义（重要）
|
||
UniqueFields 为“先查后插”的 UX 快速报错，存在 TOCTOU 竞态；并发唯一性以
|
||
数据库 uk_* 唯一索引为准（调用点必须保证对应索引存在）。
|
||
Group 语义：校验范围必须等于唯一索引范围——索引含 tenant_id 时必须
|
||
Group:"tenant_id"，否则范围取窄漏报 1062、取宽跨租户误报。
|
||
手写检查（如 user 的 username/mobile）按“被改行现租户”校验，理由相同。
|
||
|
||
4.5 模块文件结构图（以 config_item 为例）
|
||
|
||
api/v1/config_item.go
|
||
├── type ConfigItemPageReq { gmeta.Meta(get /api/config/item/page …), PageReq, 筛选字段 }
|
||
├── type ConfigItemAddReq / UpdateReq / DeleteReq / BatchDeleteReq / …
|
||
└── type ConfigItemItem / ListItem / DetailRes / …Res
|
||
internal/controller/config_item.go
|
||
└── type CConfigItem struct{}；方法转发 service.ConfigItem().Page(ctx, req)…
|
||
internal/service/config_item.go（手维护）
|
||
├── interface IConfigItem { Page/List/Detail/Add/Update/Delete/BatchDelete… }
|
||
├── var localConfigItem IConfigItem
|
||
├── func ConfigItem() IConfigItem ← controller 取用
|
||
└── func RegisterConfigItem(i IConfigItem) ← logic init 注册
|
||
internal/logic/config_item.go
|
||
├── type sConfigItem struct{}
|
||
├── var configItemSpec = ModuleSpec[…]{…} ← 差异全部进声明
|
||
├── init(){ service.RegisterConfigItem(&sConfigItem{}) }
|
||
└── 方法：三行委托基座 + 手写扩展接口（逃生舱）
|
||
internal/dao/config_item.go + dao/internal + entity + do ← 生成器/gf gen dao 产出
|
||
|
||
4.6 CRUD 流水线流程图（基座执行顺序，横切逻辑落点）
|
||
|
||
Page/List:
|
||
Model(ctx) ─▶ LikeFields ─▶ EqFields ─▶ KeywordFields ─▶ Filter ─▶ DataScope
|
||
└─ 前置：dao.Ctx 已注入 del_flag=0 + 租户 IN(0,自身)
|
||
─▶ Count ─▶ applyOrder(白名单) ─▶ .Page(pageNo,pageSize) ─▶ structRows[T]
|
||
─▶ readTransform：FileFields 补URL → MultiFileFields 补URL
|
||
→ ContentFields 展开[IMG_URL] → FillTextFields({field}Text)
|
||
─▶ AfterPageList（禁 append）／IsTree 时 List 走 buildTree
|
||
|
||
Add:
|
||
ToData(req) ─▶ BeforeAdd ─▶ saveTransform（temp→正式, 富文本占位符化）
|
||
─▶ checkUniqueRules（UniqueFields 预检，Group 支持分组唯一）
|
||
─▶ Insert（hooks: 盖章 create_*/del_flag/tenant_id，主键自增）
|
||
─▶ LastInsertId ─▶ AfterAdd ─▶ 返回 {id}
|
||
|
||
Update:
|
||
ToData(req) ─▶ BeforeUpdate（可用 MergeOld 补零值）─▶ saveTransform
|
||
─▶ checkUniqueRules(排除自身) ─▶ Update（仅更新 data 键，hooks 盖章）
|
||
─▶ AfterUpdate
|
||
|
||
Delete / BatchDelete:
|
||
BeforeDelete(守卫: 存在性/子级/引用) ─▶ Delete（deleteHook 改写 del_flag=1）
|
||
─▶ AfterDelete；批量为逐条循环 + Before/AfterBatchDelete
|
||
|
||
--------------------------------------------------------------------------------
|
||
5. 字典驱动的 {field}Text
|
||
--------------------------------------------------------------------------------
|
||
模块头部声明 SerializeMaps = map[字段]字典编码，编码规范
|
||
{模块snake}_{字段snake}（如 user_status、job_execute_policy）。
|
||
填充路径（二选一，机制同源）：
|
||
* 基座 FillTextFields：结构体存在 {Field}Text string 字段即自动填充
|
||
（反射计划按类型缓存）
|
||
* map 场景 SerializeMapOnRead(ctx, row, maps)：原地补 row[field+"Text"]
|
||
取值 DictGetText(ctx, code, value)：查 dict→dict_item 的 name，
|
||
进程内缓存 300s（dictTextCache）；未命中返回原值。
|
||
文案唯一真相在字典管理页（dict_item.name），修改最迟 5 分钟生效
|
||
（或调 GET /api/dict/refreshCache 刷新）。
|
||
例外：operation_log.type 存注解常量值，用静态表 LogTypeText
|
||
（consts.LogTypeNames），不走字典。
|
||
|
||
--------------------------------------------------------------------------------
|
||
6. 筛选对齐三件套（前端 ↔ 后端）
|
||
--------------------------------------------------------------------------------
|
||
前端 views/{域}/{模块}/querySchemas.ts 每个筛选输入后端对应：
|
||
字符串 Input（LikeFields）→ 逐列 LIKE，req 同名驼峰字段取值
|
||
Select/InputNumber（EqFields）→ 等值，零值跳过
|
||
关键词框（KeywordFields，可选）→ req.keyword 多列 OR
|
||
导出统一走 xxxSpec.applyFilters 与列表同套筛选（保证导出=所见）。
|
||
声明式之外的复杂条件写 Filter 钩子，不要重复 Like/Eq 已覆盖的条件。
|
||
|
||
--------------------------------------------------------------------------------
|
||
7. service 接口文件规范（手维护）
|
||
--------------------------------------------------------------------------------
|
||
internal/service/{模块}.go 结构：
|
||
|
||
type IXCity interface {
|
||
Page(ctx context.Context, req *v1.CityPageReq) (res *v1.CityPageRes, err error)
|
||
...
|
||
}
|
||
var localCity ICity
|
||
func City() ICity {
|
||
if localCity == nil { panic("implement not found ... forgot register?") }
|
||
return localCity
|
||
}
|
||
func RegisterCity(ic ICity) { localCity = ic }
|
||
|
||
logic 的 init() 调用 RegisterXxx；controller 通过 service.Xxx() 取用。
|
||
logic 方法签名变更时同步手工更新接口文件；禁止整体运行 gf gen service。
|
||
|
||
--------------------------------------------------------------------------------
|
||
8. 导入导出实现模式（user / level / example 启用）
|
||
--------------------------------------------------------------------------------
|
||
Import：POST multipart file（*ghttp.UploadFile + p:"file" 标签）
|
||
excel.ReadSheet 解析（首行表头，全单元格字符串，空行跳过）→
|
||
逐行映射/校验（唯一、上限、字典值）→ 批量 Insert（默认密码/角色/城市编码
|
||
等按模块规则处理）→ 返回导入统计。
|
||
Export：GET，与列表同筛选 → ChunkQuery 分批（默认 500/页，防 OOM）→
|
||
excel.WriteSheet 写临时文件 → 返回文件 URL（/upload/temp/...）。
|
||
日志：logType import/export；权限 sys:{module}:import/export。
|
||
|
||
--------------------------------------------------------------------------------
|
||
9. 跨模块共享的包级函数（logic 单包的红利）
|
||
--------------------------------------------------------------------------------
|
||
因全部 logic 同包，跨模块复用无需 import：
|
||
ResolveCityNames(ctx, codes, sep) / ResolveCityCodes(ctx, cityInfo)（city.go，
|
||
user 的 Add/Update/Import/Detail 已接入）
|
||
LoadIdentity / LoadTenant（auth.go，供中间件接线与登录路径复用）
|
||
ApplyDataScope(deptColumn)（data_scope.go，行级数据权限工厂，
|
||
spec 声明 DataScope 即接线，见 03 章第 6 节）
|
||
DictGetText / SerializeMapOnRead / FillTextFields（base.go / module_spec.go）
|
||
新增包级共享函数时注意 base.go 的“导出函数上限 15 个”纪律（超出拆子包）。
|
||
|
||
--------------------------------------------------------------------------------
|
||
10. 开发一个新模块的推荐步骤
|
||
--------------------------------------------------------------------------------
|
||
1) 设计表结构（统一审计列 + del_flag + uk_* 唯一索引 + 列注释枚举
|
||
"状态：1-正常 2-禁用"），执行 DDL
|
||
2) 用生成器生成全套文件（见 07 章），或手动按四件套模板编写
|
||
3) 调整 logic：声明 xxxSpec（筛选/树形/字典/文件字段/唯一规则）、补充扩展接口；
|
||
表含部门归属列且需行级可见性时补 DataScope: ApplyDataScope("dept_id")
|
||
4) 维护 service 接口文件与 router 注册行
|
||
5) go build ./... + gofmt + 重启；在菜单管理中为角色勾选新权限节点
|