包名必须与目录名一致且全小写无下划线，模块路径需全局唯一并含域名；二者分属不同命名层级，共同确保构建正确与远程可寻址。
包名和目录名必须一致，否则 go build 会报错
Go 编译器强制要求包声明语句中的包名（package xxx）与所在目录的名称完全一致（区分大小写），否则构建失败。这不是约定，是硬性规则。
- 错误示例：目录叫
usermanager，但文件头写package users→ 构建时报found packages users and usermanager - 正确做法：目录名改为
users，或把package声明改成package usermanager - 注意：git 仓库根目录下的
main包可以例外（目录名可为cmd/myapp，但包名仍须为main）
避免使用 Go 标准库包名，如 http、json、log
即使你写了 package json 并放在自己项目里，只要被其他代码 import "yourproject/json"，就极易和标准库 "encoding/json" 混淆，造成类型不兼容、ide 误跳转、go doc 查不到等问题。
- 常见踩坑点：新建一个
log目录封装日志工具，结果团队里有人直接import "log"却意外导入了你的包 - 解决办法：加前缀或改语义，比如
pkglog、zlog、appllog；更推荐用业务相关词，如auditlog、paymentlog - 标准库包名列表可查 https://www.php.cn/link/c336e823d31280b5ded5f32cdaa0fe0c，建议导入前先确认
小写、单个单词、简洁（user 而非 user_pkg 或 User）
Go 官方规范明确要求包名全部小写、无下划线、无大写字母。这是为了统一风格，也避免在 windows/macOS 上因大小写不敏感导致冲突（比如 User 和 user 目录被当成同一个）。
- 合法：
cache、grpcutil、idgen - 非法/不推荐：
User（首字母大写）、user_v2（含下划线）、JSONEncoder（驼峰） - 特别注意：包名不是标识符，不参与导出控制；导出与否只看首字母是否大写 —— 所以
package cache里的CacheClient仍可导出
模块路径（go.mod 中的 module 名）要全局唯一，且最好含域名
模块路径用于 import 语句，是 Go Module 体系中真正的“命名空间”。它和包名不同，但共同决定能否被正确引用和避免冲突。
立即学习“go语言免费学习笔记（深入）”；
- 错误示范：
module myproject→ 在公共代码中极易重名，go get myproject无法定位 - 正确写法：
module github.com/yourname/yourproject或module gitlab.company.com/team/project - 如果将来要开源，模块路径一旦发布就不能轻易改，否则所有依赖者都会 break；内部项目也建议按此规范，避免迁移成本
go mod init github.com/yourname/apigateway # 后续 import 就是： # import "github.com/yourname/apigateway/route" # import "github.com/yourname/apigateway/metrics"真正容易被忽略的是：包名和模块路径是两个层级的命名，各自承担不同职责 —— 包名影响本地符号可见性，模块路径决定远程可寻址性。二者都错不得，但错法不同，排查时容易只盯一个。