Go项目目录结构无强制规范，但cmd/下须按可执行名建子目录（如cmd/api），main.go仅做配置加载、依赖初始化和app.Run()调用；internal/是编译器级私有边界，外部导入即报错；测试文件必须与源码同目录同包且以_test.go结尾。
Go 项目没有强制目录结构，但随意组织会很快导致 import 路径混乱、测试失效、重构困难——尤其当多人协作或项目增长到 5k 行以上时，目录结构就不是“风格问题”，而是编译器能否正确解析包、go test 能否自动发现用例、go install 能否生成预期二进制的关键。
为什么 cmd/ 下必须按可执行名建子目录
Go 工具链通过目录名推导最终二进制名：cmd/myapp/main.go → go build 输出 ./myapp；若写成 cmd/main.go，则输出名是 ./cmd，与预期不符。更重要的是，多个命令（如 CLI 工具 + 后台 worker）必须隔离：否则 go build ./cmd 会尝试编译所有 main 包，触发 “multiple main packages” 错误。
-
cmd/下每个子目录对应一个独立可执行文件，目录名即二进制名（如cmd/steambot→steambot） -
main.go内只做三件事：加载配置、初始化依赖、调用app.Run()—— 业务逻辑必须移出 - 不要在
cmd/下放任何非main包代码；否则go list ./...会误判包路径
internal/ 不是“放私有代码的垃圾桶”，而是编译器级访问控制开关
internal/ 是 Go 语言内置的导入限制机制：任何位于 github.com/user/project/internal/foo 的包，**仅允许被 github.com/user/project/... 下的包导入**；外部模块（如 github.com/other/repo）引用会直接报错 use of internal package not allowed。这不是约定，是硬性规则。
- 把真正不该被外部依赖的实现细节放这里，比如
internal/tradebot/（含状态机、私有回调）、internal/dbmigration/ - 避免
internal/util/或internal/common/—— 这类命名等于放弃语义，最终变成函数堆砌场 - 如果某个包未来可能开源复用，就别放
internal/，改放pkg/或直接顶层（如github.com/user/project/storage）
测试文件必须和被测源码同目录，且命名严格匹配
Go 不支持集中式 test/ 目录。当你运行 go test ./...，工具链只扫描当前模块下所有 *_test.go 文件，并要求它们与同目录的非 _test.go 文件属于同一包（package xxx），否则编译失败。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
-
internal/tradebot/tradebot.go（package tradebot）的测试必须是internal/tradebot/tradebot_test.go（同样package tradebot） - 若想测私有函数，测试文件必须和源文件同包；若想测导出接口，可用
package tradebot_test（黑盒测试），但此时无法访问未导出字段或方法 - 不要手动创建
test/目录并放go test ./test—— 它根本不会运行任何测试，因为里面没有package声明或匹配的源文件
别提前建 pkg/、api/、configs/，等真有需要再加
很多模板一上来就堆满目录，结果半年过去 pkg/httputil/ 里只有两行代码，api/ 下空空如也。Go 社区共识是：“先让程序跑起来，再拆包”。小项目（main.go + go.mod 最干净；中型项目（2k 行）按功能自然分包（如 storage/、auth/）比套用 pkg/ 更直觉。
- 只有当你明确需要对外提供 SDK 或复用组件时，才考虑
pkg/；否则直接github.com/user/project/storage -
api/只在项目同时暴露 HTTP/gRPC 接口且定义需跨服务共享时才有意义（如 OpenAPI YAML、proto 文件） -
configs/应只存模板（config.example.yaml），真实配置由环境变量或启动参数注入，不进 Git
最常被忽略的一点：目录结构一旦被大量 import 语句固化，后续调整成本极高。与其花半天设计“完美结构”，不如先写清楚 tradebot.Accept() 的行为边界，再根据它自然长出 internal/tradebot/ 和 pkg/steamclient/ —— Go 的包系统是为演化服务的，不是为图纸服务的。
