53 lines
2.6 KiB
Markdown
53 lines
2.6 KiB
Markdown
# 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)
|