65 lines
2.0 KiB
Markdown
65 lines
2.0 KiB
Markdown
# 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
|
||
|
||
## 依赖方向
|
||
|
||
```text
|
||
handler → service → repository → db
|
||
utility 被任意层引用；utility 不 import internal
|
||
task → service（单向）；service 不反向依赖 task
|
||
```
|
||
|
||
禁止反向与横向环依赖；跨模块协作经同包直调或显式接口。
|
||
|
||
## 性能习惯
|
||
|
||
- 查询指定列优先（大表 SELECT * 慎用）
|
||
- 循环内不做 N+1 查询（批量 IN）
|
||
- 大结果集导出走分批，不一次载入
|
||
- 热点读经缓存（键走 consts 函数）
|
||
|
||
## 提交前
|
||
|
||
```bash
|
||
make check # fmt + vet + test-short + check-config
|
||
```
|
||
|
||
## 相关
|
||
|
||
- [12.4 模块开发规约](/zh/standards/module-code.html)
|
||
- [12.3 数据访问铁律](/zh/standards/data-access.html)
|