标准 Go 项目目录结构实战指南：深入解析 project-layout 的目录设计与落地用法

本文以 Go 社区经典参考项目 Standard Go Project Layout（标准 Go 项目目录结构）为主线，完整讲解 cmd、internal、pkg 等核心目录的职责边界、命名约定与配套目录（构建、部署、测试、CI）的组织方式，并结合仓库中的 go.mod、Makefile 和各目录说明文件给出可直接落地的项目脚手架方案。读完后你将能够：为新建或重构的 Go 项目选择合理的目录骨架，正确区分私有代码与可复用库代码，并掌握 Go Modules 时代的依赖管理要点。

项目定位：它是社区共识，而非官方标准

这个仓库描述的是 Go 应用项目的一套基础目录结构。需要先明确它的定位：

• 它不是 Go 核心开发团队定义的官方标准，而是 Go 生态中一组常见的历史项目与新项目的目录结构集合，其中一些目录模式比另一些更受欢迎；
• 官方文档中同样存在一套通用的组织指南（Organizing a Go module），其中的 internal 与 cmd 目录模式与本仓库的描述一致，可以互相印证；
• 这套布局是刻意保持通用的，它不试图强加某种特定的 Go 包结构，也不覆盖 Clean Architecture 等更细粒度的架构分层。

原文档还给出了一条非常实用的取舍建议：如果你刚开始学习 Go，或只是做一个实验性的玩具项目，这套结构过于复杂——一个 main.go 加一个 go.mod 已经绰绰有余。但随着项目增长，保持良好代码结构变得重要，否则最终会得到一堆凌乱的代码，其中包含大量隐藏的依赖关系与全局状态。当多人参与、或者你的项目被其他项目 import 时，引入 internal 私有包等常见管理方法就是最好的时机。

仓库本身的用法就是官方推荐的姿势：复制这个仓库，保留你需要的内容，删除所有用不到的内容。这些目录并不是每个项目都会全部用到，甚至 vendor 模式也不是通用的。

仓库自带的骨架：占位目录示例

从仓库的实际目录树可以看到，项目已经预置了若干带下划线的占位目录作为使用示例：

• cmd/your_app/：主应用入口的占位位置；
• internal/app/your_app/ 与 internal/pkg/your_private_lib/：内部私有代码的两层结构；
• pkg/your_public_lib/：对外发布的库代码占位；
• web/ 下进一步细分了 app、static、template 三个子目录，对应 SPA、静态资源与服务器端模板。

根目录的 go.mod 给出了模块声明模板：

module github.com/YOUR-USER-OR-ORG-NAME/YOUR-REPO-NAME

go 1.19

这里的模块路径假设项目托管在 GitHub，但这不是强制要求——模块路径可以是任意地址。需要留意的是：模块路径的首段最好包含一个「点」（.）才是合法路径。最新版 Go 已不再强制这一约束，但如果使用稍旧的 Go 版本，缺少点号的模块路径可能导致构建失败，遇到此类问题不要感到意外。

Go Modules：依赖管理的默认选择

自 Go 1.14 起，Go Modules 已是生产可用的正式特性。除非你有特定理由不使用它，否则应一律使用 Go Modules 来管理依赖——一旦使用 Go Modules，就无需再担心 $GOPATH 与项目放置位置的问题。

原文档同时给出了代码风格的配套建议：命名、格式与代码风格问题，先运行 gofmt 与主流静态检查工具（原 golint 已停止维护，推荐 staticcheck 这类受维护的 lint 工具），并阅读 Go 官方的命名与包命名指南（names.slide、effective_go 的 names 章节、package-names 博客、CodeReviewComments wiki）。仓库内另有一份繁体中文文档 README_zh-TW.md 以及简体中文 README_zh.md、README_zh-CN.md 等十余种语言翻译可供参考。

Go 核心目录详解

/cmd：主应用入口

/cmd 存放本项目的主要应用程序，其核心规则有四点：

1. 每个应用子目录的目录名应该与你期望生成的可执行文件名一致（例如 /cmd/myapp）；
2. 不要在这个目录下放置大量代码：如果你认为某些代码可以被其他项目 import 复用，放到 /pkg；如果代码不可复用、或者你不希望别人使用，放到 /internal；
3. 通常主应用只有一个很小的 main 函数，从 /internal 和 /pkg 导入并调用代码，除此之外不应该有别的逻辑；
4. 「你未来会惊讶地发现别人是怎么使用你的代码的」，所以现在就要通过目录结构明确表达你的意图。

各目录的 README 中列举了大量采用该模式的知名项目作为印证，例如 Kubernetes、Prometheus、moby、InfluxDB、Dapr、以太坊 Go 客户端的 cmd 目录组织方式——它们基本都是「极小的 main + 逻辑下沉到包」的典型。

/internal：编译器强制的私有边界

/internal 存放私有应用与库代码，即你不希望其他项目 import 的代码。这一模式的关键特性是：它由 Go 编译器本身强制执行（该机制可追溯到 Go 1.4 引入的 internal packages 特性）。把包放进 internal 目录后，只有与该目录共享公共祖先的包才能 import 它，这是 Go 文档中唯一被点名并享有编译器特殊处理的目录。

两个重要细节：

• internal 目录不必只放在项目顶层。项目目录树的任意层级都可以再包含一个 internal 子目录，因此你可以根据需要在任意深度划定私有边界；
• 可以可选地再增加一层结构，用于区分「共用」与「非共用」的内部代码。这不是必须的（对小型项目尤其如此），但视觉上能表达包的共享意图：应用代码放在 /internal/app（例如 /internal/app/myapp），多个应用共享的代码放在 /internal/pkg（例如 /internal/pkg/myprivlib）。本仓库正是按这一双层结构预置了 internal/app/your_app/ 和 internal/pkg/your_private_lib/ 两个占位目录。

/pkg：显式声明「可以对外」的库代码

/pkg 存放允许被外部应用使用的库代码（例如 /pkg/mypubliclib）。原文档特别提醒：其他项目会 import 这些库并期待它们正常工作，所以把代码放进这个目录前要三思。

pkg 与 internal 的关系值得厘清：

• internal 是更强的方案，因为它由 Go 编译器强制保证私有包不可被外部导入；
• /pkg 的价值在于显式地传达意图——「这个目录下的代码可以被其他项目安全使用」，是一种文档式的契约；
• 当项目根目录包含大量非 Go 组件时，把 Go 代码集中到 /pkg 下，还能让运行各种 Go 工具变得更简单——这一观点在多场 GopherCon 演讲中被反复提及（包括 GopherCon EU 2018 的工业级编程最佳实践、Kat Zien 的 Go 应用结构组织、GoLab 2018 的 Go 项目布局模式等）。

需要客观认识的是：/pkg 是一种常见但并非普遍接受的模式，Go 社区中有人不推荐它。原文档还追溯了其起源：早期 Go 源码本身就用 pkg 存放自己的包，随后社区项目纷纷效仿这一模式。如果项目很小、多一层嵌套没有太多价值，不使用 pkg 完全没有问题；等根目录变得杂乱（尤其是有大量非 Go 组件时）再引入不迟。仓库的 pkg/README.md 汇总了一长串采用该模式的知名项目（containerd、Istio、Kubernetes、Helm、etcd、Jaeger 等）作为生态证据。

/vendor：依赖目录与 Go Modules 的配合

应用依赖可以手工管理，或使用内置的 Go Modules 等依赖管理工具。要点如下：

• 执行 go mod vendor 命令即可生成 /vendor 目录；
• 如果 Go 版本低于 1.14，go build 时可能需要额外加上 -mod=vendor 命令行参数；从 Go 1.14 开始该参数默认启用；
• 如果你正在构建一个库，请不要把依赖提交进版本控制；
• 自 Go 1.13 起，Go 默认启用了模块代理（module proxy）功能，默认使用 proxy.golang.org 作为代理。若你的网络环境允许使用 module proxy，那么通常根本不需要 vendor 目录。

不应当拥有的目录：/src

仓库专门用一节警告：不要创建项目级的 /src 目录。这一模式通常出现在有 Java 背景的开发者身上，而你不希望自己的 Go 项目看起来像 Java 项目。

需要区分两个概念：项目层级的 /src 与 $GOPATH 工作区中的 /src。$GOPATH 环境变量指向你的工作区（非 Windows 系统默认指向 $HOME/go），工作区包含顶层的 /pkg、/bin、/src 三个目录，你的真实项目位于工作区的 /src 子目录下。因此如果项目自身再放一个 /src，最终路径会变成 /some/path/to/workspace/src/your_project/src/your_code.go 这种令人困惑的双重嵌套。即便 Go 1.11 起项目可以放在 GOPATH 之外，这也不意味着采用 /src 布局是个好主意。

服务与 Web 应用目录

/api：接口规格与协议定义

/api 目录存放 OpenAPI/Swagger 规格文件、JSON schema 文件、各种协议定义文件。它把「接口契约」与「接口实现」在目录层面分离开，方便独立演进与校验。仓库 api/README.md 中列举的采用案例（如 Kubernetes、moby 的 api 目录）印证了这种契约目录在大型服务项目中的通用性。

/web：Web 应用组件

/web 存放 Web 应用相关的组件：静态 Web 文件、服务器端模板与 SPA 相关文件。本仓库在该目录下预置了三个子目录，恰好对应这三类内容：

• web/app：SPA 前端应用产物；
• web/static：静态资源；
• web/template：服务器端渲染模板。

通用应用目录

/configs：配置模板与默认配置

/configs 存放配置文件模板或默认配置，也适合放置 confd 或 consul-template 的模板文件。它与最终生效的配置相区分——这里放的是「出厂值」和「模板」，运行时配置由配置管理系统渲染。

/init：系统初始化与进程管理

/init 存放系统初始化（systemd、upstart、sysv）与进程管理/守护（runit、supervisor）相关的配置。

/scripts：让根 Makefile 保持简单

/scripts 存放执行各种构建、安装、分析等操作的命令脚本。它们的价值在于让根目录的 Makefile 更小、更简单——本仓库的 Makefile 就是一个极端示例，全文只有一行注释：

# note: call scripts from /scripts

即所有实际逻辑都下沉到脚本目录，Makefile 仅充当入口提示。仓库 scripts/README.md 中列出的 Kubernetes Helm、CockroachDB、Terraform 等项目均采用「薄 Makefile + scripts 脚本集」的组织方式。

/build：打包与持续集成

/build 覆盖打包（Packaging）与 CI 两大类内容，官方建议的二层划分是：

• /build/package：云端镜像（AMI）、容器（Docker）、操作系统包（deb、rpm、pkg）的打包配置与脚本；
• /build/ci：CI 工具（Travis CI、CircleCI、Drone CI）的配置与脚本。注意有些 CI 工具对配置文件位置非常挑剔，尽量把文件放在 /build/ci 中，并在可行的情况下用软链接指到 CI 工具期望的位置。

/deployments：编排部署配置

/deployments 存放 IaaS、PaaS、系统与容器编排部署的配置与模板，涵盖 docker-compose、Kubernetes/Helm、Mesos、Terraform、Bosh 等。注意：在部分仓库（尤其是部署在 Kubernetes 上的应用）中，这个目录也被命名为 /deploy，两者语义相同。

/test：外部测试应用与测试数据

/test 存放额外的外部测试应用和测试数据，目录内部结构可以随意组织。两个实用细节：

• 较大的项目通常会有一个 data 子文件夹，例如 /test/data 或 /test/testdata，需要让 Go 工具忽略这些文件时优先使用这类命名；
• Go 还会忽略以 . 或 _ 开头的目录或文件，因此测试数据目录的命名拥有更大的弹性。

仓库 test/README.md 提供了进一步的示例说明。

其他目录

目录	职责	备注
/docs	设计与用户文档	补充 godoc 自动生成文档之外的内容，见 docs/README.md
/tools	本项目的支撑工具	这些工具可以从 /pkg 和 /internal 导入代码，见 tools/README.md
/examples	应用与公共库的使用范例	见 examples/README.md
/third_party	外部辅助工具、Fork 的代码及其他第三方工具	例如 Swagger UI 这类第三方静态资源
/githooks	Git hooks	存放提交前检查、格式化等钩子脚本
/assets	随仓库一起分发的其他资源	图片、Logo 等
/website	项目网站数据	适用于不使用 GitHub Pages 的场景，见 website/README.md

其中 /tools 有一条值得注意的规则：支撑工具虽然独立于主应用，但允许它复用 /pkg 与 /internal 中的代码——这说明「工具是项目内部成员」的边界划分，而不是第三方组件。

徽章（Badges）与质量工具链

原文档给出了四种常见的项目徽章用法，使用时只需把项目引用替换为你自己的仓库路径即可：

1. Go Report Card：使用 gofmt、go vet、gocyclo、golint、ineffassign、license、misspell 等工具扫描代码并在 README 展示评分徽章，适合展示代码质量概况；
2. GoDoc：原 godoc 徽章已划掉弃用（godoc.org 服务已停止），官方文档站点已由 pkg.go.dev 取代，这里仅保留历史说明；
3. pkg.go.dev：Go 包发现与文档的新入口，可以用其徽章生成工具为你的包创建文档徽章；
4. Release：展示项目最新发行版本号，把 Release 徽章中的仓库链接改指向你的项目即可。

徽章解决「展示」问题，而真正的质量保障依赖前面提到的工具链：gofmt 保证格式统一，go vet 做静态语义检查，配合 staticcheck 等受维护的 lint 工具可以发现潜在缺陷。

落地方式：复制脚手架，按需裁剪

结合仓库内容，推荐的落地流程是：

1. 克隆仓库作为起点（仅在说明克隆方式时给出仓库地址）：

   git clone https://gitcode.com/GitHub_Trending/pr/project-layout.git my-project
   

2. 按需保留目录：只写命令行工具的项目，保留 cmd、internal、scripts、Makefile 即可；构建对外库则保留 pkg；Web 服务再启用 web、api、configs、deployments；

3. 把占位目录改名落地：将 cmd/your_app/ 改为你实际的可执行文件名，将 internal/app/your_app/、internal/pkg/your_private_lib/、pkg/your_public_lib/ 改为你实际的包名；

4. 修改 go.mod 中的模块路径为你的真实仓库地址（首段建议含点号），并确认 go 1.19 这一声明与你团队的 Go 版本策略一致；

5. 依赖管理上默认走 Go Modules；仅在网络受限或需要可复现离线构建时再考虑 go mod vendor 生成 vendor 目录。

最后回到原文档的收尾提示：这套布局刻意保持通用、不强制任何特定包结构，且是一个持续演进的社区成果——如果你看到新的目录模式，或认为某个既有模式需要更新，向仓库提 issue 讨论就是贡献方式。更多带有示例与可复用配置、脚本的「更 opinionated」的项目模板仍在持续完善中，可以关注仓库动态。