Go中包名必须与目录名一致，否则工具链报错；禁用utils等泛化包名，应按职责命名；同名包需用语义化别名；模块路径是唯一标识，包名仅为末段。
包名和目录名不一致，立刻出问题
Go 不是靠 import 路径推导包名，而是看 package xxx 声明。但工具链（go list、VS Code、go test）默认期望包名与目录名完全一致。一旦不一致，就会出现“找不到包”“测试文件报错”“IDE 提示未解析导入”这类隐性故障。
- ❌ 错误示例：目录叫
authz/，但
文件里写
package auth——go build ./authz可能成功，但go test ./authz会失败 - ✅ 正确做法：目录名
authz/→ 包声明必须是package authz，且全小写、无下划线、无驼峰 - ⚠️ 注意：
go mod tidy不会帮你发现这个错误，它只管依赖路径，不管包内声明
别用 utils、common 这类泛化包名
这不是风格问题，是设计缺陷。这类名字不表达职责，导致后期功能越堆越多、边界模糊、拆分困难，最终谁都改不动。
- ❌ 错误：建一个
utils/目录，把时间格式化、字符串截断、JSON 序列化全塞进去 - ✅ 推荐：按能力切分，例如
timeutil/（专注时间处理）、strconv/（字符串转数字）、jsonx/（带默认值的 JSON 封装） - ? 简单判断法：如果包名不能回答“这个包干啥”，就该重命名。比如
config明确表示配置加载，logger表示日志封装，而helpers什么也没说
同名包冲突？用别名不是补救，是标准操作
当两个不同模块都叫 cache（比如 github.com/your/cache 和 github.com/other/cache），直接 import 会报错：“name cache already declared”。这不是 bug，是 Go 的显式设计——它强制你做出选择。
- ✅ 正确写法：
import ( "github.com/your/cache" othercache "github.com/other/cache" ) - ? 别名优先选语义化缩写，比如
redisCache "github.com/xxx/redis-cache"，而不是c1、c2 - ⚠️ 注意：别名只在当前文件生效；跨文件仍需保持一致命名习惯，否则团队协作成本飙升
模块路径才是唯一标识，包名只是“最后一段”
很多人以为改了包名就能解决冲突，其实搞混了两个概念：import path（如 "myproject/auth"）由 go.mod 的 module 声明决定；而 package auth 只是这个路径的末尾片段。真正防冲突的是完整路径，不是包名。
- ✅ 发布公共库时，用可控域名前缀：
module github.com/your-org/mylib→ 导入路径就是"github.com/your-org/mylib" - ✅ 内部项目也必须启用
go mod init，哪怕没对外发布——否则replace、require都没法用，依赖一乱就难收场 - ⚠️ 最容易被忽略的一点：如果你的
go.mod模块名是example.com/foo，但目录结构是./internal/auth，那导入路径必须是"example.com/foo/internal/auth"，不能简写成"./internal/auth"（相对导入已被弃用）
