# 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)