project-layout：Go 项目目录结构参考模板

摘要

一句话总结 golang-standards/project-layout 是一个社区驱动的 Go 项目标准目录结构指南，旨在帮助开发者在大型或协作项目中通过标准化的目录划分来组织代码和管理依赖。

核心要点

项目定位：汇集了 Go 生态中常见的目录布局模式，仅关注高层目录结构，不涉及“整洁架构”等具体的代码内部组织细节。
适用场景：适用于规模增长、多人协作、开源项目及大型真实世界应用；不适用于初学者、概念验证（PoC）或极简项目（仅需 main.go 和 go.mod 即可）。
核心代码目录：
- /cmd：主程序入口，通常代码极少，负责调用内部包。
- /internal：私有代码，受 Go 编译器强制保护，外部无法导入。
- /pkg：公共库代码，可供外部应用程序安全调用。
服务与通用目录：定义了 /api（协议与规范定义）、/web（Web 特定组件）、/configs（配置模板）、/scripts（构建/分析脚本）、/build（打包与 CI）和 /deployments（部署配置）等标准化目录。
社区认可度：虽为非官方规范，但在 Go 社区中被广泛采用，拥有超过 5.5 万 Star。
按需定制：该指南是一个高度灵活的通用模板，开发者可根据实际需求保留或删除特定目录，无需强制套用所有模式。

风险与不足

非官方标准：该布局并非 Go 核心开发团队定义的官方强制标准。
目录混淆风险：明确警告不要将 Java 生态中的 /src 目录模式带入 Go 项目，以免与 Go 工作区（GOPATH）底层的 /src 目录产生混淆。
过度设计风险：对于小型项目，引入过多的嵌套层级无法带来实际价值；同时部分目录已随技术演进而非绝对必要（例如在 Go 1.14+ 普及模块代理后，/vendor 目录已不再是必需品）。

这是一个为 Go 语言应用程序提供基础目录结构布局的指南项目。它汇集了 Go 生态系统中常见的历史和新兴项目布局模式，旨在帮助开发者更好地组织代码和管理依赖。

重要定位说明：这不是 Go 核心开发团队定义的官方标准，而是一个社区驱动的规范集合。该项目仅关注高层目录布局，不涉及如“整洁架构（Clean Architecture）”等具体的代码内部组织细节。

适用场景：随着项目规模增长、多人协作开发、开源项目，或需要明确区分私有/公共包的大型真实世界应用。
不适用场景：初学者学习 Go、概念验证（PoC）或非常简单的个人项目。在这些场景下，使用此结构会显得过度设计，通常仅需一个 main.go 文件和 go.mod 即可。

该项目定义了一系列标准化的目录结构，主要包括：

核心 Go 目录：
- /cmd：项目的主应用程序入口。通常包含极少的代码，主要负责导入和调用 /internal 和 /pkg 中的代码。
- /internal：私有应用和库代码。受 Go 编译器强制保护，外部项目无法导入此目录下的包。
- /pkg：可供外部应用程序安全使用的公共库代码。
- /vendor：应用程序依赖项（在使用 Go Modules 且不使用 module proxy 时）。
服务与 Web 目录：
- /api：OpenAPI/Swagger 规范、JSON schema 和协议定义文件。
- /web：Web 应用特定组件（如静态资源、服务端模板、SPA）。
通用应用目录：
- /configs：配置文件模板或默认配置。
- /scripts：执行构建、安装、分析等操作的脚本，有助于保持根目录的 Makefile 简洁。
- /build：打包（云、容器、操作系统包）和持续集成（CI）配置。
- /deployments：IaaS、PaaS、系统和容器编排部署配置（如 Kubernetes、Terraform）。
- /test：额外的外部测试应用和测试数据。
其他辅助目录：包括 /docs（文档）、/tools（支持工具）、/examples（示例）、/third_party（第三方工具/分叉代码）、/assets（静态资产）等。

非官方强制标准：再次强调这不是 Go 官方团队的强制标准。
避免使用 /src 目录：不要将 Java 生态中的 /src 模式带入 Go 项目中，以免与 Go 工作区（GOPATH）底层的 /src 目录产生混淆。
按需使用：并非每个项目都需要用到所有目录。例如，在 Go 1.14+ 普及 Go Modules 及模块代理（Module Proxy）之后，/vendor 目录已不再是必需品。
避免过度设计：对于小型项目，引入过多的嵌套层级可能无法带来实际价值。