Go语言代码规范指南

Go语言代码质量的关键不在表面格式，而在于error处理是否统一严谨、接口是否遵循“小而准”的调用方视角、包名是否简洁语义清晰，以及sync.Pool是否被精准用于高频稳定临时对象；文章直击常见反模式——如error裸奔、大而全的接口抽象、冗余套娃式包结构和滥用对象池，并强调：真正考验工程能力的，是每次提交前对错误处理完整性、接口必要性与包名可理解性的自觉叩问。

Go 代码好不好，不看缩进多整齐，而看 error 处理是否统一、接口是否小而准、包名是否短且语义清晰——这些地方写错，后期改起来比重写还疼。

怎么写 error 才不算“裸奔”

常见错误现象：if err != nil { panic(err) } 直接 panic，或者全用 log.Fatal 终止程序；HTTP handler 里把 err 忽略后返回空结构体，调用方根本不知道失败了。

• 所有公开函数的 error 返回值必须被显式检查，不能用下划线丢弃（除非你真确定它无关紧要）
• 不要在库函数里用 log 或 panic —— 让调用方决定怎么处理失败
• 自定义错误优先用 fmt.Errorf("xxx: %w", err) 包裹，保留原始上下文；用 errors.Is / errors.As 判断，别用字符串匹配
• HTTP handler 中，错误要转成对应状态码（如 400、500），并返回结构化 JSON，别只打日志

接口定义为什么越小越好

使用场景：写一个文件操作模块，有人定义 type FileOperator interface { Read(); Write(); Close(); Seek(); Stat(); Chmod() }，结果测试时只能 mock 全部方法，哪怕只测 Read。

• Go 接口是隐式实现的，所以接口应按「调用方需要什么」来定，不是「实现方能提供什么」
• 典型例子：io.Reader 就一个 Read([]byte) (int, error)，但 os.File、bytes.Buffer、net.Conn 都实现了它
• 别提前抽象，等出现 2–3 个相似调用点再抽接口；过早定义大接口，反而锁死实现、增加 mock 成本
• 包内私有类型尽量不用接口，直接传 struct 指针更轻量、更易追踪

包名和目录结构怎么避免“套娃”

常见错误现象：github.com/user/project/internal/handler/handler.go 里包名写 handler，结果 import "github.com/user/project/internal/handler"；或者包名用复数 handlers、带下划线 user_db。

• 包名必须是单数、小写、无下划线、无驼峰，比如 user、cache、httpcli
• 目录名和包名必须一致；internal/ 下的包不对外暴露，但命名逻辑不变
• 别为了“分类”建一堆空包：比如 model/、dto/、vo/ —— Go 没有分层强制约定，结构体放哪取决于谁用、谁维护
• 如果一个包只导出 1–2 个类型，且和另一个包强耦合（如 cache 和 cacheutil），大概率该合并

什么时候该用 sync.Pool，什么时候纯属添乱

性能影响：滥用 sync.Pool 可能让 GC 压力更大，对象生命周期变模糊，甚至引发数据残留 bug（比如没清零的 slice 被复用）。

• 只对高频分配、大小稳定、可复用的临时对象考虑 sync.Pool，典型如 []byte 缓冲、JSON 解析器实例
• 池中对象必须手动重置：从 Get() 拿到后，先清空字段或切片底层数组，再使用
• 别存含指针或闭包的结构体；别存带 finalizer 的对象；别在 init() 里预热池子（Go 1.21+ 池子已自动预热）
• 压测对比：加了 sync.Pool 后，看 go tool pprof 的 allocs/op 是否下降，GC pause 是否缩短——没明显收益就删掉

真正难的不是记住规范，而是每次 git add 前，问自己一句：这个 error 真被处理了吗？这个接口，除了我，还有谁会实现它？这个包名，别人第一次看到能猜出它干啥吗？

理论要掌握，实操不能落！以上关于《Go语言代码规范指南》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！