Standard Go Project Layout 目录规范详解从 cmd 到 vendor 的标准 Go 项目布局【免费下载链接】project-layoutStandard Go Project Layout项目地址: https://gitcode.com/GitHub_Trending/pr/project-layout本文以project-layoutStandard Go Project Layout标准 Go 项目布局仓库的布局文档为主线系统讲解该规范对/cmd、/internal、/pkg、/vendor等每一类目录的职责定义与使用边界。阅读本文后你将能够为自己或团队的 Go 项目搭建一套清晰、可扩展、且与 Go 工具链Go Modules、internal编译器约束等天然契合的目录结构并知道哪些看似合理的目录如/src应当避免。一、什么是标准 Go 项目布局定位与边界这是一份面向 Go 应用项目的基础布局basic layout。它基础有两层含义其一它只关注通用目录结构本身而不关心各目录内部具体放什么其二它的抽象层级很高不会深入指导你把项目结构得再细一点例如它不会试图覆盖Clean Architecture 这类更具体范式下的项目结构。文档中有两个必须明确的定位声明这不是 Go 核心团队core Go dev team定义的官方标准。它是 Go 生态中一系列常见的、历史性的以及正在兴起的项目布局模式pattern的集合其中一些模式比另一些更流行它是刻意保持通用的不试图强加任何一种特定的 Go 包结构。与此同时官方 Go 文档中的《Organizing a Go module》页面提供了关于如何组织 Go 项目的优质通用指南其中就包含了本布局所描述的internal与cmd目录模式两者可以相互印证。给初学者的关键告诫如果你正在学习 Go或者只是为自己构建一个概念验证PoC或简单项目那么套用这套完整布局属于杀鸡用牛刀。真正应该做的是从最简结构开始——一个main.go文件加一个go.mod就足够多。随着项目成长再逐步引入结构代码结构混乱会带来大量隐藏依赖和全局状态当多人协作时需要更多结构也到了引入管理包/库的通用方式的时候当项目是开源的、或你清楚其他项目会从你的仓库导入代码时区分私有internal包与私有代码就变得重要。文档给出的使用姿势很直接克隆仓库保留你需要的部分删掉其余一切。目录存在不意味着你必须全部使用——这些模式没有任何一个被所有项目采用连vendor模式都并非普适。1.1 与 Go Modules 的配合自 Go 1.14 起Go Modules 已可投入生产使用。除非你有特殊理由否则应当使用 Go Modules——如此便无需再操心$GOPATH与项目存放位置。本仓库根目录的 go.mod 就是一个模板module github.com/YOUR-USER-OR-ORG-NAME/YOUR-REPO-NAME go 1.19该文件默认假设项目托管在 GitHub 上但这不是硬性要求。模块路径module path可以是任意值只是路径的第一段组件名中应包含一个点——当前 Go 版本已不再强制这一点但若使用稍旧的版本缺少点号可能导致构建失败。此外文档建议把命名、格式与风格问题交给工具从运行gofmt和staticcheck开始过去作为标准 linter 的golint已弃停且不再维护建议使用 staticcheck 这类持续维护的 linter。该仓库自身就是布局的活文档根目录下除 go.mod 与各语言版 README含本文依据的 README_hi.md 印地语版外还有 Makefile、LICENSE.md、.gitignore 与 .editorconfig其余全部是承载规范语义的目录骨架。二、仓库目录总览project-layout仓库本身就是一套可直接使用的目录模板。完整结构如下含各目录职责与文档章节一一对应分类目录职责仓库中的实际形态Go 代码目录/cmd本项目的主应用每个应用一个子目录cmd/_your_app_/.keepGo 代码目录/internal私有应用与库代码编译器强制不可被外部导入internal/app/_your_app_/.keep、internal/pkg/_your_private_lib_/.keepGo 代码目录/pkg可供外部应用使用的公开库代码pkg/_your_public_lib_/.keepGo 代码目录/vendor应用依赖Go Modules 管理占位说明见 vendor/README.md服务应用目录/apiOpenAPI/Swagger 规范、JSON Schema、协议定义文件api/README.mdWeb 应用目录/web静态资源、服务端模板、SPAweb/app、web/static、web/template三个.keep占位子目录通用应用目录/configs配置文件模板或默认配置configs/README.md通用应用目录/initsystemd/upstart/sysv 与进程管理器配置init/README.md通用应用目录/scripts构建、安装、分析等脚本scripts/README.md通用应用目录/build打包package与持续集成cibuild/ci/.keep、build/package/.keep通用应用目录/deploymentsIaaS/PaaS/容器编排部署配置与模板deployments/README.md通用应用目录/test外部测试应用与测试数据test/README.md其他目录/docs设计与用户文档docs/README.md其他目录/tools项目辅助工具tools/README.md其他目录/examples应用/公开库的使用示例examples/README.md其他目录/third_party外部辅助工具、fork 代码等third_party/README.md其他目录/githooksGit 钩子githooks/README.md其他目录/assets图片、Logo 等资源assets/README.md其他目录/website项目站点数据非 GitHub Pages 时website/README.md不应存在/src——反模式见第四节——从源码结构看这个仓库不含任何真实业务代码而是用_your_app_、_your_public_lib_、_your_private_lib_这类带下划线的占位目录名明确表达此处待你填入自己的应用/库Go 工具链本身也会忽略以_开头的目录因此这些占位符不会干扰构建。三、核心 Go 代码目录/cmd、/internal、/pkg、/vendor3.1/cmd主应用入口存放本项目的主应用。每个应用对应一个子目录目录名应与你想得到的可执行文件名一致例如/cmd/myapp。核心纪律是三条不要在应用目录里堆大量代码。若某段代码可能被导入并在其他项目中使用它应放在/pkg若代码不可复用、或你不想让别人复用就放进/internal——你会对别人拿你的代码做什么感到惊讶所以要把意图表达得足够明确常见的形态是一个很小的main函数只做两件事导入并调用/internal与/pkg中的代码然后退出别无其他该目录下附带的 cmd/README.md 还给出了业界范例参照Kubernetes、Prometheus、Moby、InfluxDB、go-ethereum、Velero、Dapr 等主流项目均采用极小的main 其余逻辑全部下沉到包中的/cmd组织方式。本仓库中 cmd/ 目录下以cmd/_your_app_/.keep的形式预留了这个位置等待你的第一个应用名落地。3.2/internal被编译器强制的私有代码存放私有的应用与库代码即你不希望他人导入到自己应用或库中的代码。关键事实internal的私有性由 Go 编译器本身强制自 Go 1.4 的 release notes 起生效一个包只要位于某个internal目录之下除与其共享公共祖先的包之外其他任何包都无法导入它。它也是 Go 官方文档中唯一被点名、并获得特殊编译器待遇的目录名顶层internal并非唯一选项项目树的任何层级都可以有internal目录而且可以有多处可选地可在internal内部再加分层以区分配共享与非共享的内部代码。对小型项目这并非必需但视觉上的意图提示是有价值的/internal/app实际应用代码例如/internal/app/myapp/internal/pkg上述多个应用之间共享的私有库例如/internal/pkg/myprivlib。本仓库的骨架正是按这一可选分层预建的internal/ 下同时存在internal/app/_your_app_与internal/pkg/_your_private_lib_两个占位目录internal/README.md 进一步列出 Terraform、InfluxDB、Perkeep、Jaeger、Moby、MinIO 等项目的/internal实例以及 Waypoint 的/internal/pkg实例作为参照。3.3/pkg对外承诺可用的公开库存放可供外部应用安全使用的库代码例如/pkg/mypubliclib。其他项目会带着它能正常工作的期待导入这些库因此往这里放任何东西之前都应三思。/pkg与/internal的分工需要说清楚internal是保证私有包导入不了的更优手段因为它是 Go 强制执行的而/pkg的价值在于显式地传达一种契约——该目录下的代码对他人使用是安全的。/pkg还有第二个实用价值当根目录充斥着大量非 Go 组件和目录时把 Go 代码集中到一处能让运行各类 Go 工具构建、检查、生成等更容易。需要如实指出的争议性/pkg是一个常见但并非普遍接受的模式Go 社区中有人不推荐它pkg/README.md直言每个使用它的主流仓库都能找到十个不用的。对确实很小、多一层嵌套并不增加价值的应用项目可以完全不用它等到项目变大、根目录变拥挤尤其有大量非 Go 组件时再引入。/pkg的历史渊源也值得一提早期 Go 源码自身就用pkg存放其包社区中的各类 Go 项目随后纷纷效仿这一模式Brad Fitzpatrick 有推文可以佐证这一背景。本仓库 pkg/README.md 收录了一份很长的采用者清单代表性项目包括 Kubernetes、Moby、Helm、Grafana、CockroachDB、InfluxDB、etcd、Dapr、Cilium、Flux、K3s、Delve 等足以说明该模式的实际流行度。仓库内对应骨架为pkg/_your_public_lib_/.keep。3.4/vendor依赖管理存放应用依赖——可以手工管理也可以用你偏好的依赖管理工具或者内置的 Go Modules 管理。go mod vendor命令会替你生成/vendor目录。两个实操要点若你使用的不是 Go 1.141.14 中 vendor 模式默认开启go build时可能需要显式加上-modvendor标志如果你在构建一个库而非应用不要把应用依赖提交进仓库。另一条重要背景自 Go 1.13 起Go 默认启用了模块代理module proxy默认代理为 proxy.golang.org。如果你的场景与约束都能被模块代理满足那么可以完全不需要vendor目录。四、反模式你不应该拥有的目录/src文档单独辟出一节讨论你不应该拥有的目录目前列出的正是/src一些 Go 项目确有src目录但这通常发生在开发者来自 Java 世界src在 Java 里是常见模式的情况下。文档建议能克制就克制不要照搬这个 Java 模式——你并不真的想让 Go 代码或 Go 项目长得像 Java注意区分两种/src项目级的/src目录与 Go 为工作区workspace使用的$GOPATH下的src后者见官方《How to Write Go Code》文档。$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是好主意。本仓库的目录结构中不存在任何/src目录与这一条保持一致。五、服务与 Web 应用目录/api、/web5.1/api存放OpenAPI/Swagger 规范、JSON Schema 文件、协议定义文件protocol definition files。api/README.md 给出的业界范例是 Kubernetes 与 Moby 的/api目录——两者都把它用作对外 API 定义OpenAPI、gRPC 等协议文件的集中存放处而非 Go 实现代码。5.2/web存放Web 应用专属组件静态 Web 资产、服务端模板、单页应用SPA。本仓库将其细分为三个预置子目录各以.keep文件占位web/app/SPA 应用代码web/static/静态资源CSS/JS/图片等web/template/服务端渲染模板。六、通用应用目录/configs、/init、/scripts、/build、/deployments、/test6.1/configs配置文件模板或默认配置。文档特别指出confd或consul-template的模板文件应放在这里——即面向动态配置管理config management场景的模板而不是硬编码的生产配置。6.2/init系统初始化systemd、upstart、sysv与进程管理器/监管器runit、supervisord的配置。6.3/scripts执行各种构建、安装、分析等操作的脚本。文档强调这些脚本的作用是让根级 Makefile 保持小而简单文中以 Terraform 的根级 Makefile 为例。这一理念在本仓库中得到了直接的源码级印证——根目录 Makefile 的全部内容只有一行注释# note: call scripts from /scripts即根 Makefile 被刻意压缩到只剩指针所有实质操作下沉到/scripts。scripts/README.md 列出的参照项目为 Helm、CockroachDB、Terraform。6.4/build打包Packaging与持续集成CI分两个子目录/build/package云AMI、容器Docker、操作系统deb、rpm、pkg等打包配置与脚本/build/ciCITravis、Circle、Drone 等配置与脚本。注意部分 CI 工具例如 Travis CI对配置文件的存放位置非常挑剔尽可能把配置文件放在/build/ci下再从 CI 工具期望的位置建立链接指过来如果实在做不到配置文件留在根目录也无妨。仓库中build/ci/.keep与build/package/.keep两个占位文件即对应这两个子目录build/README.md 给出的实例是 CockroachDB 的/build目录。6.5/deploymentsIaaS、PaaS、系统与容器编排的部署配置与模板docker-compose、kubernetes/helm、terraform 等。文档补充了一个命名观察一些仓库尤其使用 Kubernetes 部署的应用会把该目录叫作/deploy——两种命名在生态中并存选一种并保持一致即可。6.6/test额外的外部测试应用与测试数据与包内_test.go单测互补。/test的内部结构可以任意组织大项目建议设数据子目录例如/test/data或/test/testdata——若需要 Go 工具链忽略该目录内容用testdata这个约定名即可。另请注意Go 同样会忽略以.或_开头的目录/文件因此测试数据目录的命名有更大灵活度。test/README.md 举了 OpenShift 的例子其测试数据放在/testdata子目录。七、其他目录/docs、/tools、/examples、/third_party、/githooks、/assets、/website/docs设计与用户文档在 godoc 自动生成的文档之外。docs/README.md 的参照项目为 Hugo、OpenShift、Dapr。/tools本项目的辅助工具。注意这些工具可以导入/pkg和/internal中的代码因为它们在同一个模块/仓库内受internal规则保护的同时仍可被自己使用。参照项目为 Istio、OpenShift、Dapr。/examples应用和/或公开库的示例代码。参照项目为 nats.go、docker-slim、Packer。/third_party外部辅助工具、fork 过的代码、以及其他第三方工具例如 Swagger UI。用于把不是自己写的、但必须随仓库携带的代码隔离在这一层。/githooksGit 钩子pre-commit、pre-push 等。/assets随仓库走的图片、Logo 等资源。/website若不使用 GitHub Pages这里就是存放项目站点数据的地方。website/README.md 的参照项目为 Vault、Perkeep。八、徽章Badges建议文档最后给出了项目 README 上可挂的徽章清单使用时把示例中的github.com/golang-standards/project-layout替换成你自己的项目引用即可Go Report Card——会用gofmt、go vet、gocyclo、golint、ineffassign、license、misspell扫描你的代码并生成报告GoDoc原文档中已用删除线标记为废弃项——godoc.org 提供的 GoDoc 在线文档托管已被弃用pkg.go.dev——目前 Go 代码发现与文档的新去处可用其徽章生成工具生成徽章Release——展示项目最新 release 版本号把链接指向你的仓库 releases 页即可。这些徽章的价值与本文主题一致在仓库门面README上公开你的质量与文档状态降低他人理解项目布局与质量的成本。九、小结把它当作菜单而非教条标准 Go 项目布局的文档通篇贯穿三个使用原则值得在收尾时再强调一次按需裁剪克隆仓库后保留你需要的删掉其余一切没有任何模式被所有项目采用意图显式化用/cmd、/internal、/pkg的划分把哪些代码允许被导入这件事表达成仓库结构本身其中internal由编译器兜底、pkg由约定兜底小项目别过度设计学习期与 PoC 阶段main.gogo.mod足矣等根目录变得拥挤、团队扩大、项目被外部导入时再让这套布局逐步长出来。配套动作命名与风格问题交给gofmt与staticcheckgolint已停止维护根 Makefile 保持指针化脚本下沉到/scripts避免引入 Java 式的/src。按此执行你得到的就是一套与 Go Modules 时代工具链天然兼容、且社区读者一眼能读懂的目录结构。【免费下载链接】project-layoutStandard Go Project Layout项目地址: https://gitcode.com/GitHub_Trending/pr/project-layout创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考