Go项目目录结构无V1/V2版本，cmd/与internal/是互补分工：cmd/按可执行名建子目录以控制二进制名并避免multiple main packages错误；internal/是编译器级私有边界，外部导入即报错。
Go 项目目录结构没有 V1/V2 版本号，所谓“V1 与 V2”是误用概念——它不是 Go 语言或工具链的版本迭代，而是社区在不同阶段形成的实践收敛，本质是工程复杂度上升后对职责划分的自然响应。
为什么不能把 cmd/ 和 internal/ 当成“旧版/新版”？
两者不是替代关系，而是互补分工：
-
cmd/是 Go 工具链硬性约定的入口组织方式：每个子目录名决定生成的二进制名（cmd/api→api），且避免multiple main packages错误 -
internal/是编译器级访问控制机制：路径中含/internal/的包，外部模块导入会直接报错use of internal package not allowed，这不是约定，是 Go 源码解析器强制执行的规则 - 早期小项目常把
main.go放根目录，看似“简单”，实则埋下隐患：一旦要拆出 CLI 工具、worker、migration 等多个命令，就必须重构成cmd/，否则go build ./cmd会失败
pkg/ 和 internal/ 的边界在哪？
关键判断标准不是“代码复用频率”，而是“是否允许被其他模块 import”：
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 放
pkg/：打算开源、被其他项目依赖的通用能力，比如pkg/httpclient、pkg/trace—— 它们有独立的go.mod（可选）、文档和测试，对外暴露明确 API - 放
internal/：仅当前项目使用的实现细节，比如internal/payment/gateway/alipay—— 即使逻辑很通用，只要不打算开放给外部调用，就该放这里；否则未来重构时，外部依赖会立刻断裂 - 警惕
internal/util：这类命名等于放弃设计意图，最终变成函数堆砌场；应按业务域建包，如internal/order/validator、internal/user/locker
go test ./ 为什么会找不到测试？
根本原因不是路径写错，而是违反了 Go 的包发现规则：
立即学习“go语言免费学习笔记（深入）”；
- 测试文件必须和被测源码在**同一目录**，且文件名以
_test.go结尾（如service/user.go对应service/user_test.go） - 测试文件的
package声明必须和源码一致：user.go是package service，则user_test.go也必须是package service（白盒测试）或package service_test（黑盒测试） - 不存在全局
test/目录：若把所有测试塞进test/unit/，go test ./完全不会扫描它，因为 Go 不识别该路径为合法包 - 运行
go test ./...时，...表示递归查找所有子目录下的包，但前提是每个子目录都构成一个合法包（含.go文件且package声明有效）
真正容易被忽略的是：目录结构一旦偏离 Go 工具链预期，问题不会立刻报错，而是在协作、CI 构建、依赖注入或静态分析时逐步暴露——比如 golangci-lint 扫不到 internal/ 下的包，或 go list ./... 返回空结果，此时再回头改结构，成本远高于初始化时花十分钟对齐规范。
