Standard Go Project Layout 实战指南构建规范化的 Go 项目目录结构【免费下载链接】project-layoutStandard Go Project Layout项目地址: https://gitcode.com/GitHub_Trending/pr/project-layout本文基于project-layout仓库的官方文档README_es.md西班牙语版标准 Go 项目布局文档展开系统讲解一套面向真实应用的 Go 项目目录组织模式核心 Go 目录cmd/internal/pkg/vendor、服务与 Web 应用目录api/web、通用支撑目录configs/init/scripts/build/deployments/test、辅助目录docs/tools/examples等以及应当避免的反模式目录src。读完后你可以直接克隆该仓库作为骨架裁剪出适合自己项目的目录结构并理解每个目录的适用场景与编译器层面的约束原理。一、这套布局的定位社区惯例而非官方标准文档在开头明确了两点定位这不是 Go 核心团队定义的官方标准。它是 Go 生态中长期形成、不断涌现的一组常见项目布局模式的集合其中一些模式比其他模式更流行。它还在若干小型增强点之外提供了对足够大的真实世界应用都常见的若干支撑目录。它刻意保持通用并不试图强制某种特定的 Go 包结构。文档给出的分阶段演进建议值得原样继承学习 Go、做 PoC 或玩具项目时这套布局是“过度设计”。从一个真正简单的结构开始即可——单个main.go文件就足够了。项目增长后要保证代码结构良好否则最终会得到一堆隐藏依赖和全局状态纠缠在一起的混乱代码。多人协作时需要更多结构此时引入一套管理包/库的通用方式变得重要。开源项目、或你明确知道其他项目会 import 你的仓库代码时必须区分私有包即internal与公开代码。文档还给出了一个非常实用的落地姿势克隆仓库保留你需要的部分删除其余所有内容。目录存在不代表你必须全部使用——没有任何一个模式适用于所有项目连vendor模式都不是普遍存在的。与 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文档特别说明了go.mod中模块路径module path的取值规则仓库中的基础go.mod假定项目托管在 GitHub但这不是硬性要求模块路径可以是任意值但路径的第一个组件名中应当包含一个点当前版本的 Go 已不再强制校验但若使用稍旧的 Go 版本缺少点号会导致构建失败而不应感到意外。代码风格工具链当你需要在命名、格式和风格上获得帮助时文档建议从运行gofmt和golint开始并配套阅读 Go 代码风格指南effective_go的命名章节、官方博客的 package names 文章、Go CodeReviewComments 维基、rakyll 的 Go 包风格指南等。此外文档还推荐了一系列 GopherCon 主题演讲作为延伸阅读Peter Bourgon 的Best Practices for Industrial ProgrammingGopherCon EU 2018、Ashley McNamara 与 Brian Ketelsen 的 Go 最佳实践GopherCon Russia 2018、Edward Muller 的 Go 反模式GopherCon 2017、Kat Zien 的How Do You Structure Your Go AppsGopherCon 2018以及一篇关于包导向设计与架构分层的中文文章《面向包的设计和架构分层》。需要补充一个仓库内的版本差异事实英文版主 READMEREADME.md中已将golint更新为已废弃deprecated状态并推荐使用受维护的staticcheck替代。如果你的项目基于较新工具链建议以该表述为准。二、核心 Go 目录/cmd主应用入口/cmd存放本项目的主应用程序。关键规则是每个应用的目录名应与你期望得到的可执行文件名一致例如/cmd/myapp。文档强调不要把大量代码放在应用目录里如果认为某段代码可以被其他项目导入使用 → 放到/pkg如果代码不可复用、或你不想让别人复用 → 放到/internal。文档原话提醒“你会惊讶于其他人会拿你的代码做什么所以明确表达你的意图” 常见的做法是只写一个很小的main函数import 并调用/internal和/pkg目录中的代码除此之外什么都不做。本仓库自身就示范了这一结构cmd/下有一个占位目录cmd/_your_app_/其说明见 cmd/README.md。该子文档还列举了大量采用此模式的主流项目Velero、Moby、Prometheus、InfluxDB、Kubernetes、Dapr、go-ethereum 等作为参照。/internal编译器强制的私有代码/internal存放私有的应用和库代码——即你不希望其他项目 import 的代码。这里的关键词是这种布局模式由 Go 编译器本身强制执行其历史可追溯到 Go 1.4 版本发布说明中引入的 internal packages 特性。两个重要的结构性事实文档明确指出internal不局限于顶层目录——你可以在项目树的任意层级拥有多个internal目录放在internal目录下的包只有与其共享公共祖先common ancestor的包才能导入它是 Go 官方文档中唯一被具名并享有特殊编译器待遇的目录。文档同时建议可选、非必须小项目尤其可以跳过为内部包增加一层额外结构以分离“共享”与“非共享”的内部代码——实际应用代码放在/internal/app例如/internal/app/myapp这些应用共享的代码放在/internal/pkg例如/internal/pkg/myprivlib。本仓库按此建议搭建了骨架internal/README.md 及internal/app/_your_app_/、internal/pkg/_your_private_lib_/两个占位目录其示例项目包括 Terraform、InfluxDB、Perkeep、Jaeger、Moby、Satellity、MinIO 等/internal/pkg的示例则引用了 Waypoint。/pkg对外公开的库代码/pkg存放可以被外部应用安全使用的库代码例如/pkg/mypubliclib。文档的告诫同样直白“其他项目会 import 这些库并期待它们正常工作所以在放东西到这里之前三思。”关于/pkg与/internal的分工文档给出两点判断internal是确保私有包不可被导入的更好手段因为它由 Go 编译器强制执行/pkg的价值在于显式传达“该目录下的代码供他人使用是安全的”这一意图。此外/pkg还有工程上的附带收益当你的根目录混杂了大量非 Go 组件与目录时把 Go 代码归拢到一处可以让运行各种 Go 工具变得更简单这一点在 GopherCon EU 2018、GopherCon 2018、GoLab 2018 等演讲中均有提及。文档也如实记录了社区争议/pkg是一个常见但并非被普遍接受的模式Go 社区中有人并不推荐它。pkg/README.md 收录了超过 100 个采用此模式的知名仓库清单Kubernetes、etcd、Helm、Moby、Istio、Argo、Cilium、Thanos、K3s 等供读者自行权衡。对于很小的应用项目文档认为不用/pkg完全可以当项目变大、根目录变得“拥挤”尤其存在大量非 Go 应用组件时再考虑引入。文档还追溯了pkg目录的起源早期 Go 源码自身曾用pkg存放其包社区项目随后开始效仿这一模式。/vendor应用依赖/vendor存放应用依赖可以手工管理也可以用你喜欢的依赖管理工具如内置的 Go Modules管理。要点go mod vendor命令会为你创建/vendor目录如果使用低于 Go 1.14 的版本Go 1.14 起默认启用可能需要在go build命令上追加-modvendor标记如果你构建的是库library不要提交你的应用依赖自 Go 1.13 起模块代理module proxy功能已启用默认使用 Go 官方模块代理服务器作为默认代理。如果你的需求与约束都满足可以完全不需要vendor目录。三、服务类与 Web 类应用目录/api存放 OpenAPI/Swagger 规范、JSON schema 文件、协议定义文件。本仓库提供了 api/README.md其中列举了 Kubernetes 与 Moby 的api目录作为范例。/web存放 Web 应用特有组件静态 Web 资源、服务端模板和 SPA。仓库中已给出web/的三层骨架——web/app、web/static、web/template对应 web/README.md 中的三类内容。四、通用应用目录/configs存放配置文件模板或默认配置也包括confd或consul-template的模板文件。/init存放系统初始化配置systemd、upstart、sysv和进程管理器/监管者配置runit、supervisord。/scripts存放执行构建、安装、分析等各类操作的脚本。这些脚本的作用是让根级 Makefile 保持小而简单文档以 Terraform 的 Makefile 为参照。本仓库的 Makefile 只有一行注释——# note: call scripts from /scripts——正是这一理念的落地构建逻辑全部下沉到scripts/目录。scripts/README.md 中列举了 Helm、CockroachDB、Terraform 的scripts目录作为示例。/build打包与持续集成云AMI、容器Docker、操作系统deb、rpm、pkg的打包配置与脚本 →/build/packageCItravis、circle、drone的配置与脚本 →/build/ci。注意某些 CI 工具如 Travis CI对配置文件位置非常挑剔尽量把配置文件放在/build/ci并链接link到 CI 工具期望的位置。/deployments存放 IaaS、PaaS、系统与容器编排的部署配置和模板docker-compose、kubernetes/helm、mesos、terraform、bosh。文档提醒在一些仓库尤其是用 Kubernetes 部署的应用中这个目录被称为/deploy。本仓库采用的是deployments/命名见 deployments/README.md。/test存放额外的外部测试应用和测试数据目录内部结构可以随意组织。对较大的项目设一个数据子目录是有意义的。文档还指出了 Go 构建工具的两条“忽略规则”让你有更多命名自由使用/test/data或/test/testdataGo 会忽略该目录中的内容testdata是被 Go 工具链特殊对待的目录名Go 还会忽略以.或_开头的目录或文件。test/README.md 以 OpenShift Origin 的test目录测试数据位于/testdata子目录作为示例。五、其他辅助目录目录用途仓库内对应物/docs设计与用户文档godoc 生成的文档之外的补充。示例Hugo、OpenShift、Daprdocs/README.md/tools本项目的辅助工具。注意这些工具可以导入/pkg和/internal中的代码。示例Istio、OpenShift、Daprtools/README.md/examples应用和/或公开库的示例examples/README.md/third_party外部辅助工具、fork 的代码、其他第三方工具例如 Swagger UIthird_party//githooksGit hooksgithooks//assets随仓库附带其他资源图片、logo 等assets//website若不使用 GitHub Pages这里是项目网站数据的存放地。示例Vault、Perkeepwebsite/README.md六、你不应该拥有的目录/src文档专门辟出一节警告某些 Go 项目会有src文件夹但这通常发生在开发者来自 Java 世界、沿用了 Java 惯用模式时——“你真的不希望你的 Go 代码或 Go 项目长得像 Java。”文档同时澄清了一个常见混淆不要把项目级的/src目录与 Go 工作区中的/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之外但这仍然不意味着这种布局是好主意。七、如何把这份布局落为自己的项目结合文档内容与仓库实际内容推荐的操作路径是克隆仓库保留所需目录删除其余部分。仓库根目录下的完整目录清单api/、assets/、cmd/、configs/、deployments/、docs/、examples/、githooks/、init/、internal/、pkg/、scripts/、test/、third_party/、tools/、web/、website/本身就是这套布局的可复制清单按项目阶段裁剪单人学习项目只需main.gogo.mod多组件应用至少保留cmd/internal/开源或被外部 import 的项目再加上pkg/修改模块路径把 go.mod 中的module声明改为你的真实模块路径确保第一级组件名中含有点号兼容旧版 Go 的保险做法用scripts/承接构建逻辑让根级 Makefile 保持一行注释式的极简形态用徽章建立质量信号文档的 Badges 一节推荐了 Go Report Card用gofmt、go vet、gocyclo、golint、ineffassign、license和misspell扫描代码将其中项目引用替换为你的项目即可、Pkg.go.dev新的 Go 文档与发现入口可用其徽章生成工具制作徽章、以及展示最新版本号的 Release 徽章原 GoDoc 徽章已划去废弃因为 Pkg.go.dev 取代了它的文档展示职能。文档末尾的 Notes 一节还透露了一个进行中WIP的计划一个对配置、脚本和示例代码更有主见的more opinionated项目模板正在建设中适合作为进阶参考。八、要点回顾该布局是社区模式集合而非官方标准核心价值在于团队一致性与显式意图表达cmd目录名即产物名main保持最小化internal是编译器强制的私有边界可在任意层级出现internal/appinternal/pkg是可选的进一步分层pkg传达“公开契约”的意图存在社区争议小项目可不用vendor由go mod vendor生成低版本 Go 需-modvendor库项目不应提交依赖configs/init/scripts/build/deployments/test覆盖运维与测试全链路其中testdata与.、_前缀是 Go 工具链的忽略规则明确不要在 Go 项目中使用/src。【免费下载链接】project-layoutStandard Go Project Layout项目地址: https://gitcode.com/GitHub_Trending/pr/project-layout创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考