2.0 KiB
2.0 KiB
12.8 后端编码规范
:::tip 建议遵守 在数据访问铁律与模块规约之上，后端编码的通用风格约定：命名、注释、错误、并发、依赖方向。 :::
命名
| 对象 | 规约 | 示例 |
|---|---|---|
| 模块文件 | 小写下划线，与表名对应 | user.go、dict_item.go |
| 控制器 | C + 模块名 Pascal | CUser |
| 服务 | s + 模块名 | sUser |
| 仓储 | 模块名 + Repo | UserRepo |
| 声明变量 | 模块名 + Spec | userSpec |
| 常量 | 语义化大驼峰 | CodeRecordNotFound |
| 缓存键 | consts 键函数生成 | CacheKeyCaptcha(uuid) |
注释
- 包注释一句说明模块职责；文件头不加横幅
- 导出函数注释以函数名开头，说明行为/约束/降级
- 反直觉处（顺序依赖、红线原因）必须注释"为什么"
- 注释直述现状，不写改造过程与来源对比
错误处理
- 业务失败用哨兵/apperr，原样上抛不 wrap
- 不吞错只记日志；日志与返回二选一时优先返回
- panic 仅限编程错误（如 ToData 类型不匹配）——运行时输入不 panic
并发
- service 单例方法必须并发安全（无请求态字段）
- ctx 贯穿一切（身份/事务/追踪），不用全局变量传请求态
- 缓存读写经 utility/cache（自带降级），不直连 go-redis
依赖方向
handler → service → repository → db
utility 被任意层引用；utility 不 import internal
task → service（单向）；service 不反向依赖 task
禁止反向与横向环依赖；跨模块协作经同包直调或显式接口。
性能习惯
- 查询指定列优先（大表 SELECT * 慎用）
- 循环内不做 N+1 查询（批量 IN）
- 大结果集导出走分批，不一次载入
- 热点读经缓存（键走 consts 函数）
提交前
make check # fmt + vet + test-short + check-config