Go项目结构虽无编译器强制要求，但cmd/需按可执行名建子目录、internal/为编译器级私有边界、测试文件须与源码同目录同包、文件拆分应以单一主题为单位——这些是工程能否构建和测试成功的前提。
Go 项目结构没有编译器强制要求，但目录组织方式直接影响 go build 是否成功、go test 能否自动发现用例、多人协作时 import 路径是否稳定——这不是风格问题，是工程能否跑起来的基础。
cmd/ 下必须按可执行名建子目录
Go 工具链靠目录名决定最终二进制名：cmd/api/main.go → go build 输出 ./api；若写成 cmd/main.go，输出就是 ./cmd，和预期不符。更关键的是，多个命令（如 CLI + worker）共存时，go build ./cmd 会报 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/ 下的包导入**；外部模块引用直接报错 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），否则编译失败。
立即学习“go语言免费学习笔记（深入）”；
-
internal/tradebot/tradebot.go（package tradebot）的测试必须是internal/tradebot/tradebot_test.go（同样package tradebot） - 若想测私有函数，测试文件必须和源文件同包；若想黑盒测导出接口，可用
package tradebot_test，但此时无法访问未导出字段或方法 - 不要把测试文件放在
test/目录下 ——go test根本不会识别它
文件拆分应以“单一主题”而非“单个方法”为单位
Go 鼓励一个文件聚焦一个逻辑主题，而不是为每个方法新建文件。参考标准库 net/http/server.go（约 2200 行），它把整个 HTTP server 的核心逻辑收在一个文件里，靠清晰的注释和空行分段。
- 例如
tradebot包下：trade_actions.go放acceptTrade()、declineTrade()、sendTrade()等语义紧密关联的方法 -
monitoring.go放monitorTrade()、startMonitoring()、stopMonitoring()等协同行为 - 每文件保持 300–800 行为宜；过短（如每个方法一个文件）导致 import 泛滥、跳转成本高；过长（>1500 行）则难以定位和维护
真正容易被忽略的，是 internal/ 的编译器级限制和 go test 对文件位置的硬性要求——这两点不满足，项目连基本构建和测试都跑不起来，比命名规范或注释风格要致命得多。
