Golang项目目录结构规划建议

本文深入解析了Go语言项目标准化目录结构的最佳实践，强调根目录应严格仅保留go.mod和go.sum文件，彻底摒弃将main.go置于项目顶层的常见误区；通过清晰划分cmd/（多入口可执行文件）、internal/（模块内私有、不可外部导入的核心业务逻辑）与pkg/（真正解耦、可跨项目复用的公共组件）三大关键目录，并辅以测试数据隔离（testdata/）、子包分层原则及边界管控策略，系统性地解决了项目初期结构混乱、后期扩展困难、测试污染主逻辑、复用性差等高频痛点——早一天规范结构，就少一分重构成本，多一分面向微服务演进与规模化协作的底气。

Go 项目根目录下不要放 main.go 直接跑

很多新手把 main.go 放在 GOPATH 或模块根目录下，用 go run main.go 能跑通就以为没问题。但这样会导致：
– 无法被其他包 import（因为顶层包名是 main）
– 模块初始化混乱（go mod init 易误设为非规范路径）
– 后续加测试、CLI 子命令、HTTP 服务等时结构迅速失控
正确做法是：根目录只放 go.mod 和 go.sum，所有代码进 cmd/、internal/、pkg/ 等子目录。

cmd/ 下按可执行文件分目录，每个含独立 main.go

一个 Go 模块常对应多个二进制输出（比如 CLI 工具 + 后台服务 + 数据迁移脚本）。cmd/ 是存放这些入口的标准位置：
– 每个子目录名即最终二进制名（如 cmd/myapp → go build -o myapp cmd/myapp）
– 每个 cmd/*/main.go 的包声明必须是 package main
– main.go 只做参数解析和启动，业务逻辑全部下沉到 internal/
示例结构：

cmd/
├── api-server/
│   └── main.go
├── migrate/
│   └── main.go
└── cli/
    └── main.go

internal/ 和 pkg/ 别混用：内部逻辑与可复用组件要隔离

internal/ 下的代码只能被本模块导入（Go 编译器强制限制），适合放核心业务、领域模型、私有工具函数；pkg/ 则用于导出给外部模块复用的公共能力（如通用 HTTP 客户端、配置解析器）。常见错误：
– 把数据库操作封装进 pkg/ 却依赖本项目特定的 struct（导致外部无法使用）
– 在 internal/ 里写大量泛用工具函数，结果其他项目想抄又抄不了（因无法 import）
建议：
– internal/app/：应用层编排（如 handler、service）
– internal/domain/：纯业务逻辑与实体（不依赖框架）
– internal/infrastructure/：DB、缓存、消息队列等具体实现
– pkg/encoding、pkg/version 等：真正解耦、无项目强依赖的模块

测试文件和 testdata/ 放哪？别让测试污染主逻辑路径

Go 测试文件（*_test.go）必须和被测文件同目录，这是语言要求。但测试用的 fixture 文件、mock 数据不能塞进 internal/ 或 pkg/ —— 会增大构建体积、暴露内部路径。正确方式：
– 所有测试数据统一放在根目录下的 testdata/（Go 官方推荐，且 go test 默认忽略该目录）
– 在测试中用 filepath.Join("testdata", "config.yaml") 加载
– 如果某个子包需要专属测试数据，可在其同级建 testdata/（如 internal/domain/testdata/），但需确保不被 go build 打包进去
注意：testdata/ 不是 Go 标准约定目录，不会被自动识别或处理，全靠你手动管理路径和清理逻辑。

Go 项目结构没有银弹，但越早约束 cmd/、internal/、pkg/ 的边界，后期加中间件、切微服务、做单元测试的成本就越低。最常被忽略的是：internal/ 下的子目录层级不是越多越好，而是按“谁会同时修改它”来聚类——比如 internal/infrastructure/db 和 internal/infrastructure/cache 可以并列，但别硬拆成 db/postgres 和 db/mysql，除非你真要同时支持两种驱动。

今天关于《Golang项目目录结构规划建议》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！