go语言以包为作用域单元，包名须小写、简短、语义明确，避免util等泛化名，推荐按功能聚类如payment、domain，版本升级应通过模块路径而非子目录或自造包名。
Go 语言没有传统意义上的“命名空间”，包（package）是代码组织和作用域隔离的基本单元。因此，包名本身承担了命名规范、可读性和冲突规避的核心责任。合理设计包名，不是风格偏好，而是影响项目可维护性、导入清晰度和团队协作效率的关键实践。
包名应小写、简短、语义明确
Go 官方强制要求包名全部使用小写字母（不支持下划线或驼峰），且建议控制在 1–2 个单词内。过长或模糊的包名会降低可读性，也容易与其他包重复。
- ✅ 推荐：
http、sql、cache、auth、userrepo（强调用途而非结构） - ❌ 避免：
UserRepository（含大写）、user_repository（含下划线）、userdatabaseaccesslayer（过长难读） - 注意：包名不必与目录名完全一致，但强烈建议保持一致——这是 Go 工具链（如
go list、ide 导入提示）默认依赖的约定。
避免通用名冲突：用前缀或上下文限定范围
像 util、common、base 这类泛化包名极易引发冲突，也掩盖了真实职责。一旦多个模块都定义 util，导入时必须重命名（如 myutil "github.com/me/proj/util"），破坏简洁性。
- ✅ 改进方式：按功能边界加业务/模块前缀，例如
paymentutil、apiclient、logconfig - ✅ 或按层级细化：将通用工具下沉到具体场景中，如
internal/httpclient、internal/encoding/jsonx - ⚠️ 特别提醒：
internal包天然受 Go 访问控制保护（仅本模块可导入），适合放真正内部、非复用的辅助逻辑，避免误导外部使用者。
按功能聚类，而非技术分层来命名包
Go 社区更倾向“领域驱动”的包组织方式，而非 mvc 或 service/repository 这类分层命名。一个包应围绕一个明确职责展开，名字要让人一眼看出“它管什么”，而不是“它在哪一层”。
立即学习“go语言免费学习笔记（深入）”；
- ✅ 推荐结构示例：
cmd/（入口）、api/（HTTP handler）、domain/（核心模型+业务规则）、storage/（数据持久化抽象）、payment/（支付专属逻辑） - ❌ 不推荐：
controller、service、dao——这类名字未说明业务含义，多个服务共用时极易同名且语义空洞。 - 关键判断标准：如果把包名替换成“XXX 功能”，句子是否自然？例如
payment→ “处理支付功能”，成立；service→ “处理 service 功能”，不成立。
版本与兼容性：慎用 v2+ 子目录，优先用模块路径区分
当需要不兼容升级时，常见误区是在同一仓库内建 /v2 子目录并声明新包名（如 github.com/me/lib/v2）。这虽可行，但易导致包名重复（v2 包仍叫 lib），且增加用户导入负担。
- ✅ 更清晰的做法：通过模块路径体现主版本，同时保持包名简洁。例如：
v1 模块：github.com/me/lib，包名lib
v2 模块：github.com/me/lib/v2，包名仍为lib（Go 会自动识别为不同模块） - ✅ 若需保留旧版兼容，可用别名导入：
import v1 "github.com/me/lib"，配合文档说明差异。 - ⚠️ 避免：
libv2、lib2等自造包名——违背小写简短原则，也失去模块系统对版本的原生支持。