Go包名必须全小写、单数、无下划线、无驼峰且与目录名严格一致，否则工具链（go build/test、gopls等）无法正确识别依赖和执行构建。
Go包名必须全小写、单数、无下划线、无驼峰，且与目录名严格一致——这不是风格建议，是工具链正常工作的前提。
为什么package utils是危险信号
它不表达职责，只暗示“这里塞了点杂项”。真实项目里，utils目录往往演变成垃圾场：字符串处理、时间格式、HTTP工具、错误包装全挤在一起。后期想拆分？函数间强耦合，导出符号命名冲突（比如FormatTime和FormatDate都导出为Format），重构成本极高。
更实际的问题是 IDE 和 go list 无法准确推断依赖边界。当你执行 go test ./...，工具会把所有 utils 子目录当成独立包扫描，但它们又没声明正确包名，直接报错或跳过。
- ✅ 替代方案：按领域切分，
strutil（仅字符串操作）、timeutil（仅时间转换）、httpx（仅 HTTP 辅助逻辑） - ✅ 若只有 2–3 个函数，优先合并进调用方主包，而非新建包
- ⚠️ 特例
errors是标准库抽象，不是你建utils的借口
package auth 放在 auth/ 目录下才真正生效
Go 编译器不强制校验包名与目录名是否一致，但 go build、go test、gopls、VS Code 跳转全部依赖这个约定。你硬写 package authz 在 auth/ 目录里，go list ./auth 仍能识别，但 CI 脚本跑 go test ./... 时会漏掉这个包，因为路径匹配逻辑默认取目录名作包标识。
立即学习“go语言免费学习笔记（深入）”；
- 目录结构是
internal/cache/redis/→ 包名必须是redis，不是cache_redis - 目录结构是
cmd/myapp/→ 包名必须是main，且该目录下只能有main.go和其他.go文件（不能混入config.go声明package config） - 模块路径是
github.com/you/app，那么auth/下的导入路径就是github.com/you/app/auth，包名仍是auth
别为避免重名加前缀，比如 package myprojectdb
Go 的唯一性靠导入路径保证，不是包名。标准库有 net，你自己的网络封装也可以叫 net，只要导入路径不同（如 github.com/you/internal/net），就完全合法。强行加项目前缀只会让调用变冗长：myprojectdb.Open() vs db.Open()，而真正决定可读性的，是变量名和函数签名，不是包名。
- ✅ 正确做法：包名保持简短，冲突时用导入别名解决，
import mydb "github.com/you/app/db" - ❌ 错误做法：改包名为
projectdb或v2db——v2不表达语义，还和模块版本路径（/v2）混淆 - ⚠️ 绝对禁止：用
package type、package map、package nil—— 这些是预声明标识符，会导致后续代码编译失败
package main 只能出现在可执行入口，且一个模块内应唯一
它不是“主逻辑包”的代称，而是 Go 工具链识别二进制输出的标记。你在 pkg/ 或 internal/ 下建 package main，go build 会静默忽略，go list 报错，CI 流水线可能构建出错误的二进制。
- ✅ 正确结构：
cmd/myapp/main.go（package main），internal/server/（package server），pkg/config/（package config） - ❌ 多个
main包共存于根目录：go build默认构建第一个找到的，行为不可控 - ❌ 把工具函数塞进
main包：其他包无法 import，只能复制粘贴，违背复用原则
最难的不是记住规则，而是每次新建目录时克制住想“说得更清楚”的冲动——httpclient 比 myprojecthttpclientv2 更可靠，因为工具链认它，人读它不费力，而“清楚”该由文档和函数名承担。
