12.8 后端编码规范

建议遵守

在数据访问铁律与模块规约之上，后端编码的通用风格约定：命名、注释、错误、并发、依赖方向。

命名

对象	规约	示例
模块文件	小写下划线，与表名对应	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

相关