Golang包名命名避坑：防止标准库冲突

Go语言包名命名看似简单，实则暗藏诸多陷阱：使用log、http等标准库名称会导致静默覆盖、功能异常；滥用util、common等宽泛词会催生难以维护的“黑洞包”；包名必须小写、单数、无下划线，且同一模块内严格唯一——哪怕路径不同，重复的package声明也会引发构建失败；测试包虽可用xxx_test避免冲突，但若在测试中误导入同名自定义包，仍可能引发解析混乱甚至循环引用。真正棘手的不是规则本身，而是命名失范在团队中快速传染、积重难返，最终让重构变成一场耗时耗力的全局grep与手动重命名攻坚战。

Go 包名不能叫 log、http、json 等标准库名字

编译会通过，但 import 时会覆盖标准库，导致 log.Println 调不到原生函数，或 http.ServeMux 找不到类型定义。这不是冲突报错，而是静默覆盖——你写的 log 包一旦被同目录其他文件 import，整个模块里所有对 log 的引用都会指向你的包。

• 常见翻车场景：新建项目想封装日志，随手建 log/ 目录，放个 log.go，再在 go.mod 里声明 module myproj/log
• 标准库包名列表以 go list std 输出为准，包括 fmt、os、io、sync、time 等 40+ 个，建议直接查，别凭记忆
• 别以为加前缀就安全，比如 mylog 没问题，但 logv2 或 log_ext 仍可能让团队误判，不如直接叫 logger

包名别用 util、common、base 这类宽泛词

这类名字不表达职责，导致后续没人敢往里加新功能（怕“污染”），也不敢删旧代码（怕别人偷偷依赖），最后变成无人维护的黑洞。更重要的是，Go 的包导入路径就是包名来源，github.com/you/proj/util 这种路径会让调用方写 util.DoX()，完全看不出逻辑归属。

• 优先按领域或功能命名：payment、notify、cache，哪怕初期只有 2 个文件
• 如果真要抽象工具函数，按用途拆：比如时间处理放 timeutil，字符串处理放 strutil，而不是全塞进一个 util
• 包名小写、单数、无下划线，config 可以，configs 或 my_config 不推荐

同一模块内包名不能重复，即使路径不同

Go 编译器认的是包名（package xxx 声明），不是目录路径。比如 internal/a/log/log.go 和 internal/b/log/log.go 都声明 package log，构建时会报 duplicate package "log"，哪怕它们物理路径完全不同。

• 错误常发生在重构时：把原 log 包拆成多个子包，但忘了改 package 声明
• 解决办法只有两个：统一改成带前缀的包名（如 alog、blogger），或用语义化子包（log/writer、log/rotate），主包仍叫 log，子包用 package writer
• go list -f '{{.Name}}' ./... 可快速扫出当前模块所有包名，人工去重比靠报错更省时间

测试文件里的 package xxx_test 不算新包名，但要注意导入歧义

xxx_test 是合法且推荐的测试包声明方式，它不会和 package xxx 冲突。但如果你在 xxx_test.go 里又 import 了同名包（比如自己写了 log 包并 import 它），而测试文件本身是 package log_test，那 log 就既指标准库，又指你自己的包，Go 会优先解析为当前模块内的 log，导致测试跑不通。

• 测试文件中若需用标准库 log，显式重命名导入：import stdlog "log"
• 避免在测试文件里 import 和自身包名相同的自定义包，比如 cache/cache_test.go 里 import "myproj/cache" —— 这容易引发循环引用或解析混乱
• 测试包名唯一作用是隔离标识，不参与构建产物，所以不用纠结它是否“好听”，保持 xxx_test 即可

事情说清了就结束。最麻烦的从来不是命名规则本身，而是团队里有人写了 util，其他人看见就跟着仿，一两个月后满项目都是 util、utils、common_util，改起来得逐个 grep + 手动 rename。

理论要掌握，实操不能落！以上关于《Golang包名命名避坑：防止标准库冲突》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！