签入版本

2026-10-25 17:24:27 +08:00
parent 48911cc08f
commit fdbeae092a
1010 changed files with 30682 additions and 95274 deletions
@@ -0,0 +1,52 @@
+# 12.4 模块开发规约
+
+:::tip 必须遵守
+一个模块固定四个文件（dto / repository / service / handler），对外 JSON 契约（json 标签、字段名、路径、权限码、binding 标签）以表结构与前端约定为准，保持稳定。本页是规约全文要点。
+:::
+
+## dto — internal/model/dto/{module}.go
+
+- 结构体按职责命名（UserItem、UserPageReq…），json 标签即对外 API 字段名
+- 每字段补 `form:"同json名"` 标签；binding/msg 与 dc 注释按校验需求书写
+- 时间字段统一 `*LocalTime`；文件字段 `*multipart.FileHeader` + UnmarshalBody
+- 分页公共字段内嵌 PageReq；批量删除用 `Ids []int64`
+- 类型别名：`type XxxListRes = []*XxxItem`、`type XxxPageRes = PageData[XxxItem]`
+- 路由声明在 router.go 该控制器的 RouteSpec 表（字段 Method/Path/Summary/Permission/Log/LogType/Public），新增接口补一条，写法与既有条目逐字一致
+
+## repository — internal/repository/{module}.go
+
+```go
+type XxxRepo struct{ Base }
+func NewXxxRepo() *XxxRepo { return &XxxRepo{Base: NewBase("gin_xxx")} }
+func (r *XxxRepo) Ctx(ctx context.Context) *gorm.DB { return r.Base.Ctx(ctx) }
+```
+
+表名 = gin_ + 模块名；关联表同样建仓储。铁律见 [12.3 数据访问铁律](/zh/standards/data-access.html)。
+
+## service — internal/service/{module}.go
+
+- 三段式：`type sXxx struct{}` + init 注册 + `var Xxx *sXxx`
+- 标准七方法委托 ModuleSpec；复杂逻辑（导入导出、登录、分配菜单）手写方法
+- 跨模块同包直调（无需 import）；dict 相关模块 init 调 SetDictLookup
+- 数据权限需要的模块声明 `DataScope: ApplyDataScope("dept_id")`
+- 事务：`db.WithTrans(ctx, func(ctx context.Context) error { ... })`
+- 业务错误：`consts.CodeXxx` 哨兵或 `apperr.Newf(consts.CodeXxx.Code(), "fmt", a...)`
+- 钩子禁 HTTP/文件 IO、禁 append；错误原样上抛
+
+## handler — internal/handler/{module}.go
+
+- 极薄委托：`type CXxx struct{}` + 与 dto 一一对应的方法
+- 签名固定 `func (c *CXxx) Method(ctx context.Context, req *dto.XxxReq) (*dto.XxxRes, error)`
+- 非标准方法（导入/导出/重置密码/分配菜单等）保留为 handler 方法并注释入参/返回/副作用
+
+## 通用禁则
+
+- 注释一律按当前功能直述
+- 文件头不加版权横幅，仅包注释一句说明模块职责
+- binding/msg 标签逐字保持（本项目 validator 读取该标签）
+- 新增配置键必须同步 .env.example
+
+## 相关
+
+- [第 3 章 模块开发实战](/zh/guide/overview.html)
+- [3.11 完整代码清单](/zh/guide/code-list.html)