Standard Go Project Layout

项目简介

Standard Go Project Layout 是 Go 社区中流传最广的项目目录结构参考模板。它汇总了 Go 生态里常见的历史与新兴目录约定，并给出每个目录的职责说明，帮助开发者在项目变大、协作人数变多时保持代码结构清晰。

需要强调：它不是 Go 官方核心团队定义的标准，而是一份社区共识性质的布局参考。官方关于模块组织的建议可参考 Go 文档中的 Organizing a Go module。

核心目录约定

应用与私有代码

• /cmd：各可执行程序的入口，目录名通常与生成的二进制名一致，例如 /cmd/myapp。这里只放少量 main 函数代码，真正的逻辑应下沉到 internal 或 pkg。
• /internal：私有代码，Go 编译器会强制限制外部模块导入，是保护内部实现的可靠方式。可在任意层级设置多个 internal 目录。
• /pkg：允许被外部项目导入的公共库代码。放入前需谨慎，因为一旦公开就意味着要维护兼容性。

常见支撑目录

• /api：OpenAPI、Protobuf 等接口定义
• /configs：配置模板与默认配置
• /deployments 或 /deploy：容器与编排部署描述
• /test：额外的测试数据与集成测试辅助
• /scripts：构建、安装、分析等脚本
• /docs：设计文档与用户文档
• /web、/assets：Web 静态资源与前端资产

使用方式

该仓库本身是一个模板，推荐做法是按需取用：

1. 克隆或浏览仓库，理解各目录职责；
2. 只保留当前项目真正需要的目录；
3. 删除其余空目录与示例文件；
4. 结合团队规范补充 README 与 CI 配置。

一个最小可用的 Go 项目其实只需要：

myapp/
├── go.mod
└── main.go

当项目增长、出现多人协作或需要对外提供库时，再逐步引入 cmd、internal、pkg 等结构。

适用与不适用

适合：中大型服务、需要长期维护的开源项目、多人协作的团队项目。

不适合：学习 Go 的练手项目、概念验证（PoC）、个人小工具。这类场景从单个 main.go 加 go.mod 起步更高效。

补充建议

• 命名与格式优先使用 gofmt 与 staticcheck，golint 已废弃。
• 项目结构应服务于可读性与依赖管理，而非为了“看起来规范”堆砌目录。
• 仓库提供简体中文、繁体中文、日文、韩文等多语言 README，中文开发者可直接阅读中文版。