Go标准项目布局完全指南：基于 project-layout 仓库的目录蓝图深度解析

本篇技术指南以 Go 社区标准项目布局（Standard Go Project Layout）的简体中文说明文档为主体，系统讲解 cmd、internal、pkg、vendor 等核心目录的用途与选型依据，并结合仓库中的 go.mod、Makefile、.gitignore 及各目录的 README 佐证实际结构。读完本篇，你将能够为一个真实 Go 项目设计清晰的目录骨架，明确每类代码该放在哪里、为什么这样放，以及如何避免最常见的反模式。

定位：它是社区共识，不是官方标准

需要先明确一点：这套布局不是 Go 核心团队定义的官方标准，而是 Go 生态中大量经典项目与新兴项目反复出现的一组常见项目布局模式的集合，属于社区共同努力的产物。其中有些模式比其他模式更受欢迎，仓库通过几个支撑目录为“足够大规模”的实际应用程序提供一些增强功能，但布局本身有意设计得比较通用，不尝试引入任何特定的 Go 包结构——它只规定“目录放什么”，不规定“代码怎么组织”。

使用它时的几点原则（来自文档原意）：

• 小项目不要照搬全套。如果你正准备学习 Go、构建 PoC 或写玩具项目，按全套布局组织属于大材小用——一个 main.go 文件就足够了。随着项目增长，再确保代码结构合理，否则会积累大量隐藏的依赖关系和全局状态，导致代码混乱。
• 多人协作时才真正需要清晰结构。当一个项目多人同时进行、维护开源项目或有其他项目导入你的代码时，清晰的包结构与私有包（如 internal）就变得非常重要。
• 按需取用：克隆这个项目，保留你需要的部分，删除其余部分。通常不需要、也没有必要使用全部内容——从来没有哪个真实项目在单一仓库中使用过这里定义的全部模式（vendor 模式也是如此）。
• 如果发现新的模式或已有模式需要更新，正确做法是为项目新建一个 issue，而不是私改结构。

模块前提：Go Modules 与 go.mod

文档明确说明：Go 1.14 起 Go Modules 已可用于生产环境，没有特殊原因就应该使用 Go Modules。使用它之后，你再也不必担心 $GOPATH 配置和项目实际存放位置，项目想放在哪里就放在哪里。

当前仓库的 go.mod 恰好是这一原则的落地示例，全文只有两行：

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

go 1.19

两个值得注意的细节：

1. module 路径占位符。文档指出 go.mod 中的内容假设项目托管在 GitHub 上——这里的占位符 github.com/YOUR-USER-OR-ORG-NAME/YOUR-REPO-NAME 正是此意。但这不是必选项：Module 路径可以是任意值。一般约定是 Module 路径的第一部分应包含一个点（如 github.com）；最新版 Go 已不再强制要求这一点，但在稍旧的 Go 版本中可能因缺少点而编译失败（相关讨论可见 Go 官方 issue #37554 与 #32819）。
2. 声明的 Go 版本。go.mod 声明 go 1.19，印证了文档所述“Go Modules 已是生产级基础设施”的前提——现代 Go 工具链默认以模块模式工作。

目录总览

仓库根目录实际包含的布局目录（每个目录均附带一份 README 说明）如下：

目录	用途类别	说明文件
cmd/	主应用入口	每个可执行程序的 main 包
internal/	私有代码	编译器强制不可被外部导入
pkg/	公共库代码	允许外部项目安全导入
vendor/	应用依赖	go mod vendor 产物
api/	服务端	OpenAPI/Swagger、协议定义
web/	Web 应用	静态资源、模板、SPA
configs/	通用	配置模板、默认配置
init/	通用	systemd 等系统初始化配置
scripts/	通用	构建、安装、分析脚本
build/	通用	打包与持续集成
deployments/	通用	IaaS/PaaS/编排部署配置
test/	通用	外部测试应用与测试数据
docs/	其他	设计与用户文档
tools/	其他	项目支持工具
examples/	其他	应用与公共库示例
third_party/	其他	fork 代码与第三方工具
githooks/	其他	Git 钩子
assets/	其他	图像、Logo 等资源
website/	其他	项目网站数据

仓库中这些目录以 .keep 占位文件保留空结构（如 cmd/_your_app_/.keep、internal/pkg/_your_private_lib_/.keep、pkg/_your_public_lib_/.keep、build/ci/.keep），即克隆后直接获得一份可填写的空骨架。

Go 目录

/cmd：主应用入口

项目主要的应用程序放在 /cmd 下，且每个应用目录的名字应与期望的可执行文件名一致（例如 /cmd/myapp）。核心约束是：不要在 /cmd 里放太多代码。cmd/README.md 的判定规则很直接：

• 代码如果可以被其他项目导入使用 → 放 /pkg；
• 代码不可重用或不希望被他人使用 → 放 /internal。

文档特别强调“显式地表明意图”——因为你无法预料别人会怎么使用你的目录。通常的做法是：项目拥有一个小的 main 函数，它只导入并调用 /internal 和 /pkg 中的代码，除此之外什么都不做。当前仓库用 cmd/_your_app_/ 占位目录演示了这一结构（_ 前缀同时被 Go 工具链忽略，避免占位符被当作包解析）。

/internal：编译器强制的私有代码库

/internal 存放不希望被其他人导入的私有应用代码。与 /pkg 最大的区别在于：这种“不可导入”的约束是 Go 编译器本身强制执行的（该机制自 Go 1.4 引入）。两个实践要点：

1. internal 不限于顶层目录。项目目录树的任意层级都可以有 internal 目录，而不只是一个顶层目录；
2. 可选地在内部代码中再加一层结构来分隔“共享”与“非共享”的内部代码——应用代码放 /internal/app（如 internal/app/myapp），应用间共享的代码放 /internal/pkg（如 internal/pkg/myprivlib）。这并非必须（小项目尤其如此），但为包用途提供了直观的视觉线索。

从本仓库结构看，这两层占位目录均已就位：internal/app/_your_app_/.keep 与 internal/pkg/_your_private_lib_/.keep，与 internal/README.md 的说明一一对应。

/pkg：对外承诺可用的公共库

/pkg 存放外部应用程序可以安全使用的库代码（如 /pkg/mypubliclib）。其他项目会导入这些库并期望它们稳定工作，所以把代码放在这里前要三思。文档同时给出了几点重要补充：

• internal 是确保私有代码不被导入的“硬手段”（编译器强制），而 /pkg 是“软承诺”——用目录名明确告诉使用者“这里可以被安全导入”。关于 pkg 与 internal 何时各取何用的取舍，社区有一篇广为引用的文章《I'll take pkg over internal》可以延伸阅读（正文不附外链，可自行检索）；
• 当根目录包含大量非 Go 组件与目录时，/pkg 也是把 Go 代码聚拢到一处的手段，让运行各种 Go 工具变得更容易。这一点在多篇知名演讲中被提及（GopherCon EU 2018 的《Best Practices for Industrial Programming》、GopherCon 2018 Kat Zien 的《How Do You Structure Your Apps》、GoLab 2018 Massimiliano Pippi 的《Project layout patterns in Go》）；
• 该模式存在争议：pkg/README.md 坦承，每有一个流行仓库使用它，就能找到十个不用的；但不管好坏，更多人能看懂你的意图。若项目很小、多一层嵌套价值不大，就可以不用它；当项目变大、根目录变得杂乱（尤其含大量非 Go 组件）时再认真考虑。
• 一个有趣的来源考据：pkg 目录的起源可追溯到早期 Go 源码自身用 pkg 存放包，随后社区项目纷纷效仿。

/vendor：依赖管理

/vendor 存放应用程序的依赖关系（手动维护、依赖管理工具，或内置的 Go Modules）。关键操作与注意事项：

• 执行 go mod vendor 会在项目中创建 /vendor 目录；
• 若使用的不是 Go 1.14，执行 go build 时需要显式添加 -mod=vendor 命令行选项（它并非默认值）；
• 构建库时不要提交依赖项（"Don't commit your application dependencies if you are building a library"）；
• 自 Go 1.13 起，模块代理（module proxy）特性启用，默认使用 proxy.golang.org。如果 Go Modules 加模块代理满足需求，就完全不需要 vendor 目录。

本仓库的 .gitignore 印证了这一点：# Dependency directories (remove the comment below to include it) 下一行是被注释掉的 # vendor/——即默认不忽略 vendor，把是否将依赖纳入版本控制的决定权交给使用者。

服务端应用的目录

/api

存放 OpenAPI/Swagger 规范、JSON Schema 文件、协议定义文件。仓库占位见 api/README.md，适用于定义 API 契约的 API 网关、微服务等场景。

Web 应用的目录

/web

Web 应用特定组件：静态 Web 资源、服务器端模板与单页应用（SPA）。从本仓库结构看，/web 被细分为三个子目录占位：web/app/、web/static/、web/template/，分别对应单页应用代码、静态资源与模板，结构直观。

通用应用的目录

/configs

配置文件模板或默认配置，同时是放置 confd 或 consul-template 模板文件的位置。

/init

系统初始化（systemd、upstart、sysv）与进程管理器（runit、supervisord）的配置。

/scripts

用于执行各种构建、安装、分析等操作的脚本。这些脚本的核心价值是让根级 Makefile 保持更小更简单。仓库根目录的 Makefile 是绝佳证据——整个文件只有一行注释：

# note: call scripts from /scripts

即构建细节全部下沉到 scripts/ 中的脚本里，Makefile 只负责调用。这正是文档中“以 Helm/Terraform 等项目 Makefile 为参照”理念的极简示范。

/build

打包和持续集成两个子区：

• /build/package：云（AMI）、容器（Docker）、操作系统（deb、rpm、pkg）软件包配置与脚本；
• /build/ci：CI（Travis、CircleCI、Drone）配置文件与脚本。注意一些 CI 工具对配置文件位置有严格要求，文档建议把配置放进 /build/ci，再用链接指向 CI 工具期望的位置；若保持放在根目录更方便，也可以不拘泥。

仓库实际以 build/ci/.keep 与 build/package/.keep 保留这两个子目录，说明见 build/README.md。

/deployments

IaaS、PaaS、系统与容器编排的部署配置和模板（docker-compose、kubernetes/helm、mesos、terraform、bosh）。文档提醒：在某些仓库（尤其是使用 Kubernetes 部署的应用）中该目录名为 /deploy。

/test

外部测试应用程序和测试数据，目录结构可自由组织。大项目建议设数据子目录：若需要 Go 忽略目录内容，可用 /test/data 或 /test/testdata 命名。另注意 Go 同样会忽略以 . 或 _ 开头的目录或文件，因此测试数据目录的命名有更大灵活性。

其他

/docs

设计与用户文档（godoc 生成的文档除外）。

/tools

本项目的支持工具。注意这些工具可以从 /pkg 和 /internal 导入代码——这一说明很重要，它划清了工具代码与应用代码的引用边界。

/examples

应用程序或公共库的使用示例。

/third_party

外部辅助工具、fork 的代码及其他第三方工具（例如 Swagger UI）。

/githooks

Git 钩子。

/assets

项目配套的其他资源（图像、Logo 等）。

/website

如果不使用 GitHub Pages，则在这里放置项目网站数据。

不应该出现的目录

/src

有一些 Go 项目确实包含 src 文件夹，但通常只有开发者从 Java 转过来的时候才会这样（src 是 Java 的通用模式）。如果可以，请不要使用这种 Java 模式——你肯定不希望 Go 代码看起来像 Java。

同时要区分两个概念：项目级的 /src 目录，与 Go 工作空间（workspace）的 /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 布局是个好主意。

根目录工程细节：仓库给出的隐性规范

除目录外，模板仓库的根文件也编码了若干工程约定，值得在采纳布局时一并参考：

1. .editorconfig：统一多编辑器格式——charset = utf-8、LF 换行、文件末尾保留换行、去除行尾空白；Go 源码、Makefile、go.mod 使用 tab 缩进，YAML/JSON 用 2 空格，前端代码用 4 空格，Markdown 保留行尾空白（用于双空格换行）。这基本就是 Go 项目的格式基线。
2. .gitignore：忽略 Mac 的 .DS_Store、各类二进制产物（*.exe、*.dll、*.so、*.dylib）、go test -c 产出的 *.test、覆盖率输出 *.out，并预留了 vendor 的注释开关。
3. .gitattributes：* -text，禁止 Git 自动进行换行符转换，保证各平台检出内容一致。

风格与徽章

文档建议：需要关于命名、格式化或样式的帮助时，先运行 gofmt 和 golint，并阅读 Go 社区的经典风格资料，包括 Effective Go 的命名章节、Go 官方博客的包命名文章、Go 代码评审意见 wiki，以及多场 GopherCon 演讲（工业级编程最佳实践、Go 反模式、如何组织 Go 应用结构等）。

关于 README 徽章，文档推荐三类：

• Go Report Card：使用 gofmt、vet、gocyclo、golint、ineffassign、license、mispell 扫描项目代码，使用时把 github.com/golang-standards/project-layout 替换为你的项目引用；
• GoDoc：提供 godoc 生成文档的在线版本，链接指向你的项目；
• Release：显示项目最新版本号。

使用方式小结

结合文档与仓库现状，落地这套布局的推荐路径是：

1. 将本仓库克隆到本地（模板即骨架），按项目需要保留目录、删除其余部分——小项目从 cmd/ 一个目录起步完全合理；
2. 在 go.mod 中把 module 路径占位符 github.com/YOUR-USER-OR-ORG-NAME/YOUR-REPO-NAME 换成真实模块路径，并按需调整 go 版本声明（当前模板为 1.19）；
3. 按“可复用 → /pkg、私有 → /internal、入口 → /cmd”的规则放置代码，并用 internal 的编译器强制特性保护私有实现；
4. 依赖管理优先使用 Go Modules 与模块代理；确需离线构建或锁定依赖时再执行 go mod vendor（旧版本 Go 记得加 -mod=vendor）；
5. 工程脚本下沉到 scripts/，保持 Makefile 精简；部署、CI、打包配置分别归位到 deployments/、build/ci、build/package；
6. 避免引入 /src 这一 Java 风格反模式。

最后说明：该布局文档本身处于持续演进中（原 README 末尾的“注意”一节标注其为 WIP——一个带有示例配置、脚本与代码的项目模板），各目录模式欢迎通过 issue 提出新的实践，这也是社区协作维护该标准的既定方式。