Go 标准项目布局详解project-layout 仓库的目录规范、适用边界与源码级实践【免费下载链接】project-layoutStandard Go Project Layout项目地址: https://gitcode.com/GitHub_Trending/pr/project-layoutproject-layout 仓库定义了 Go 生态中最具影响力的社区级项目目录模板。本文以仓库中的文档为主体完整覆盖/cmd、/internal、/pkg、/vendor等 Go 核心目录以及/api、/configs、/deployments等服务与通用目录的定位规则并结合仓库内的go.mod、Makefile与各目录 README讲清楚每个目录“放什么、为什么不放别的目录”、何时该采用该布局、Go Modules 与internal机制如何从编译器层面保障包边界以及为什么/src是 Go 项目中应当回避的反模式。一、定位社区共识模板而非 Go 官方标准在使用这个布局之前必须首先明确它的性质——文档中用粗体反复强调了这一点它是 Go 生态中历史形成与正在兴起的项目布局模式的集合其中一些模式比另外一些更流行它不是 Go 核心开发团队定义的官方标准官方文档中有独立的、更具权威性的项目组织指南官方 Go 文档中的 “Organizing a Go module” 一页涵盖了internal与cmd等目录模式本模板是在此基础上的社区补充并额外收录了大型真实应用中常见的一些辅助目录它刻意保持通用化不试图强加某种具体的 Go 包结构例如它不尝试覆盖 Clean Architecture 之类的内部结构方案。1.1 适用边界小项目直接用会“过度设计”文档给出了非常明确的适用建议这一点值得原样继承如果你正在学习 Go或者只是在做一个PoC / 个人小项目这个布局属于过度设计overkill。从最简单的形态开始即可——一个main.go文件加上go.mod就足够了。文档同时给出了引入结构化布局的三个触发信号项目开始增长需要保证代码结构清晰否则最终会得到一堆隐藏依赖和全局状态global state混杂的烂代码多人协作需要更强的结构约束此时应当引入一种管理包/库的通用方式开源或被其他项目 import必须理解创建私有包internal的重要性明确对外与对内的代码边界。对于已经决定采用的团队文档给出的操作建议是“克隆仓库保留你真正需要的部分删掉其余的一切”——目录的存在不等于必须使用没有任何一个模式要求在每个项目里全部出现连vendor都不是万能的。1.2 模板的多语言维护该模板被翻译为十几种语言仓库根目录维护了完整的语言索引含中文、日文、韩文、法文、西班牙文、葡萄牙文等例如 中文 README、日文 README、英文原版 等。各语言版本内容基本对齐阅读任一版本均可但请注意个别版本之间可能存在措辞差异例如英文原版已把 lint 工具建议从golint更新为staticcheck而部分语言版本仍停留在golint的表述。二、Go Modulesgo.mod与模块路径的硬性要求从 Go 1.14 开始Go Modules 正式达到生产可用。文档的建议是除非有明确的理由不用否则一律使用 Go Modules使用了 Modules你就不再需要关心$GOPATH的值和项目应该放在哪里。2.1 仓库中的基准go.mod仓库根目录自带一个最小化的 go.mod其完整内容只有两行module github.com/YOUR-USER-OR-ORG-NAME/YOUR-REPO-NAME go 1.19从这个文件可以读出三个关键信息模块声明module行声明了项目的导入路径。仓库给出的示例以github.com开头这只是假定项目托管在 GitHub 上并非硬性要求——模块路径可以是任何合法的 Go 导入路径Go 版本声明go 1.19声明了本模块使用的 Go 语言版本工具链会据此选择对应的语言特性集合占位符约定YOUR-USER-OR-ORG-NAME/YOUR-REPO-NAME是提示读者替换为自己组织/仓库名的占位符克隆模板后第一步就应修改它。2.2 模块路径“首段必须含点”的历史约束文档特别指出一个容易踩坑的历史约束模块路径的第一个组件中应当包含一个点例如github.com中的com。当前版本的 Go 已经不再强制这一点但如果你使用的是稍旧的 Go 版本缺少这个点会导致构建失败——文档建议遇到此类构建异常时先检查这里并查阅上游问题跟踪中的 37554 与 32819 两个议题以了解更多背景。三、仓库目录树总览从源码结构看本仓库自身就是模板的实例每个顶层目录对应布局中的一个约定目录目录内以 README 说明职责以_前缀占位目录示意命名规范。仓库的实际顶层结构如下project-layout/ ├── api/ # OpenAPI/Swagger 规格、JSON schema、协议定义文件 ├── assets/ # 与仓库配套的其他资源图片、logo 等 ├── cmd/ │ └── _your_app_/ # 应用入口目录占位示例 ├── configs/ # 配置文件模板 / 默认配置 ├── deployments/ # IaaS/PaaS/容器编排部署模板 ├── docs/ # 设计与用户文档 ├── examples/ # 应用与库的示例 ├── githooks/ # Git hooks ├── init/ # systemd/upstart/sysv 及进程管理器配置 ├── internal/ │ ├── app/ │ │ └── _your_app_/ # 私有应用代码占位示例 │ └── pkg/ │ └── _your_private_lib_/ # 多个内部应用共享的私有库 ├── pkg/ │ └── _your_public_lib_/ # 可被外部项目安全导入的公开库 ├── scripts/ # 构建、安装、分析等脚本 ├── test/ # 额外外部测试应用与测试数据 ├── third_party/ # 外部辅助工具、fork 代码、第三方组件 ├── tools/ # 项目支持工具 ├── web/ │ ├── app/ # 单页应用SPA │ ├── static/ # 静态 Web 资源 │ └── template/ # 服务端模板 ├── website/ # 项目网站文件不使用 GitHub Pages 时 ├── Makefile # 根级 Makefile仅一行注释 ├── LICENSE.md ├── go.mod └── README*.md # 多语言版本文档其中占位目录的命名本身就携带规范信息cmd/下的_your_app_表示“每个应用的目录名应与你期望的可执行文件名一致”internal/app/_your_app_表示私有应用代码的位置internal/pkg/_your_private_lib_与pkg/_your_public_lib_分别表示私有共享库与公开库的落位。仓库根目录的 Makefile 也践行了模板自身的理念——它只有一行内容# note: call scripts from /scripts即根级 Makefile 保持极简具体构建脚本放进/scripts这一点在文档对/scripts的描述中同样有明确阐述。四、Go 核心目录/cmd、/internal、/pkg、/vendor4.1 /cmd主应用入口/cmd存放当前项目的主应用程序main applications。文档给出的三条规则目录名与可执行文件名一致每个应用的目录名应当匹配你想得到的可执行文件名例如/cmd/myapp产出myapp不要把大量代码放在应用目录里若代码可能被其他项目导入复用 → 放进/pkg若代码不可复用、或你不想让别人复用 → 放进/internal文档原话是“别人能做出什么事会让你惊讶所以明确表达你的意图”main函数应当小而精最常见的实践是一个小小的main函数只负责导入并调用/internal与/pkg中的代码除此之外什么都不做。文档在 cmd/README.md 中还列出了 velero、moby、prometheus、influxdb、kubernetes 等一批采用该模式的知名仓库可据此确认“cmd下只有小main”是工业界主流写法。4.2 /internal编译器强制的私有边界/internal存放不希望被其他应用和库导入的私有代码。这个模式有区别于其他所有目录的关键特性——它由 Go 编译器本身强制执行只要一个包位于某个internal目录之下与该包没有共同祖先的包就无法导入它。这是自 Go 1.4 起就写入语言规范的机制也是唯一被 Go 官方文档点名并给予编译器特殊待遇的目录名。文档还给出两条实操补充internal不限于顶层你不受限于顶层这一个internal目录可以在项目树的任意层级拥有多个internal目录可选的二级结构可以为内部包增加一层结构以区分“共享”与“非共享”代码。小项目中这不是必需的但它提供了直观的使用意图线索应用自身代码放/internal/app如/internal/app/myapp多个内部应用共享的代码放/internal/pkg如/internal/pkg/myprivlib。从源码结构看本仓库正是按这个可选结构建立的骨架internal/README.md 的说明与internal/app/_your_app_、internal/pkg/_your_private_lib_两个占位目录一一对应。4.3 /pkg公开库的显式声明/pkg存放可供外部应用安全使用的库代码如/pkg/mypubliclib。文档对其定位有几层意思承诺大于形式其他项目会导入这里的库并预期它们持续可用所以“放东西进来之前想三遍”与/internal的分工internal是更优的“防导入”手段因为它是 Go 编译器强制的/pkg的价值在于显式地向外界沟通“这个目录下的代码可以放心使用”。社区中 Travis Jeffery 的《Ill take pkg over internal》一文对二者的取舍做过很好的综述工具便利性当根目录塞满大量非 Go 组件时把 Go 代码归拢到/pkg能方便各类 Go 工具的运行这一点在 GopherCon EU 2018《Best Practices for Industrial Programming》、GopherCon 2018 Kat Zien 的分享以及 GoLab 2018 Massimiliano Pippi 的分享中都有提及社区态度/pkg是一个常见但未被普遍接受的布局Go 社区中有人不推荐它pkg/README.md 里收录了一份非常长的采用该模式的知名仓库清单containerd、kubernetes、helm、etcd、kafka 系组件等可从中评估它在你所在生态的接受度起源pkg目录的源头是老 Go 源码自身用pkg存放标准库包随后社区项目纷纷效仿Brad Fitzpatrick 曾就此有过相关说明使用门槛项目非常小、多一层嵌套没有实际价值时可以不用它当根目录变得拥挤尤其混有大量非 Go 组件时再考虑引入。4.4 /vendor依赖管理/vendor存放应用依赖——可以手工管理也可以用依赖管理工具管理如今最常用的是内置的Go Modulesgo mod vendor该命令会为你生成/vendor目录。文档给出了三条注意事项构建标志如果你使用的不是 Go 1.14该版本起-modvendor在检测到vendor目录后默认启用可能需要在go build中显式加上-modvendor标志库项目不要提交依赖如果你在构建一个库不要把你的应用依赖提交进仓库模块代理可替代 vendor自 Go 1.13 起Go 启用了模块代理特性默认使用proxy.golang.org作为代理服务器。如果该代理满足你所有的需求与约束离线环境等例外那么vendor目录可能完全不需要。4.5 三个核心目录的分工速查目录可见性谁可以导入典型内容/cmd入口不对外提供导入只产出可执行文件小而精的main函数目录名 可执行文件名/internal私有仅共享共同祖先的包编译器强制应用私有代码、内部共享库/pkg公开任何外部项目惯例承诺非编译器保证供第三方安全导入的库五、服务应用目录与 Web 目录5.1 /api接口契约文件/api存放OpenAPI/Swagger 规格文件、JSON schema 文件、协议定义文件。它是服务类项目中“契约”的落位与实现代码解耦方便前后端或微服务之间对齐。api/README.md 列出了 kubernetes、moby 等采用该模式的仓库。5.2 /webWeb 应用组件/web存放 Web 应用专属组件静态 Web 资源、服务端模板与单页应用SPA。从源码结构看本仓库将其细分为web/appSPA、web/static静态资源、web/template服务端模板三个子目录给出了一个可直接套用的三分法示例。六、通用应用目录/configs、/init、/scripts、/build、/deployments、/test6.1 /configs配置模板与默认配置/configs存放配置文件模板或默认配置。文档特别指出confd或consul-template这类动态配置渲染工具的模板文件也应放在这里。6.2 /init系统初始化与进程管理配置/init存放系统初始化配置systemd、upstart、sysv与进程管理器/守护器配置runit、supervisord。把服务化单元文件从代码目录中隔离出来是运维侧约定俗成的做法。6.3 /scripts构建与运维脚本/scripts存放执行各类构建、安装、分析等操作的脚本。它们的存在使根级 Makefile 可以保持小而简单——文档以 HashiCorp Terraform 的 Makefile 为例说明这一思路。仓库根目录 Makefile 只保留一行“请调用 /scripts 中的脚本”的注释正是该理念的直接示范更多脚本组织方式可参考 scripts/README.md 中列出的 helm、cockroach、terraform 等仓库。6.4 /build打包与持续集成/build用于打包Packaging和持续集成CI文档建议两个子目录/build/package云镜像AMI、容器Docker、系统包deb、rpm、pkg等打包配置与脚本/build/ciCI 平台travis、circle、drone的配置与脚本。需要注意的坑部分 CI 工具如 Travis CI对其配置文件的位置非常挑剔。可行的折中是把配置文件放在/build/ci再在 CI 工具期望的位置建立符号链接指向它们在工具允许的情况下。6.5 /deployments部署模板/deployments存放IaaS、PaaS、系统与容器编排的部署配置和模板典型内容包括 docker-compose、kubernetes/helm、mesos、terraform、bosh。文档同时提醒在一些仓库尤其是用 Kubernetes 部署的应用中这个目录被叫作/deploy——两种命名都能见到阅读他人项目时不必意外。6.6 /test外部测试应用与测试数据/test存放额外的外部测试应用和测试数据内部结构可自由组织。文档给出两条与 Go 工具链相关的实用细节测试数据子目录大项目建议设置数据子目录例如/test/data或者直接用/test/testdata让 Go 工具链忽略其中的文件忽略规则Go 同样会忽略以.或_开头的文件或目录因此测试数据目录的命名有更大的自由度。更多实例见 test/README.md例如 OpenShift Origin 将测试数据放在/testdata子目录中。七、其他目录/docs、/tools、/examples、/third_party、/githooks、/assets、/website7.1 /docs设计文档与用户文档/docs存放设计文档和用户文档与 godoc 自动生成的 API 文档互为补充。本仓库 docs/README.md 给出了其他项目的参考示例。7.2 /tools项目支持工具/tools存放本项目的支持工具。文档明确这些工具可以导入/pkg与/internal中的代码——这是它们与/cmd的重要区别/cmd下应当只有小main而tools是完整可执行工具。7.3 /examples示例/examples存放你的应用和/或公开库的使用示例examples/README.md 列出了若干参考项目。7.4 /third_party第三方组件/third_party存放外部辅助工具、fork 出来的代码以及其他第三方工具文档给出的例子是 Swagger UI。它与/vendor的区别在于vendor是被编译器/构建过程直接消费的依赖而third_party通常是项目流程中引用的辅助性外部组件。7.5 /githooksGit hooks/githooks存放 Git hooks提交前检查、推送校验等脚本。7.6 /assets静态资源/assets存放与仓库配套使用的其他资源例如图片、logo等。7.7 /website项目网站如果你没有使用 GitHub Pages项目网站文件放在/website。website/README.md 提供了示例参考。八、反模式为什么不应该有 /src文档专门设立了“你不应该拥有的目录”一节唯一列出的就是/src。它给出两条理由来源是 Java 习惯一些 Go 项目出现src目录通常是因为开发者来自 Java 世界——这是 Java 中常见的模式。文档直白地建议不要照搬这个 Java 模式“你不希望你的 Go 代码或 Go 项目看起来像是 Java 写的。”与 GOPATH 的/src混淆不要把项目级/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之外这仍然不改变“使用这种布局不是好主意”的结论。九、代码风格、质量工具与徽章9.1 风格工具链文档建议命名、格式化、风格问题的第一站是gofmt。lint 工具方面需要注意版本差异——英文原版已将golint标注为已弃用deprecated且不再维护推荐使用仍在维护的 lint 工具如staticcheck部分语言版本文档包括俄语版仍停留在golint的表述实践时以英文原版为准。文档同时列出了一组值得精读的风格材料2014 年的命名规范分享、effective_go中的命名章节、官方博客的包命名文章、Go 代码评审注释维基以及 rakyllJBD的《Go 包风格指南》。9.2 目录组织进阶材料围绕“包命名、组织与代码结构”文档还推荐了多场演讲GopherCon EU 2018 Peter Bourgon《工业级编程最佳实践》、GopherCon Russia 2018《Go 最佳实践》、GopherCon 2017 Edward Muller《Go 反模式》、GopherCon 2018 Kat Zien《如何组织你的 Go 应用》以及一篇关于面向包设计与架构分层的中文文章。这些材料解释了/internal、/pkg等目录约定背后的设计动机。9.3 仓库徽章Badges文档还整理了四类适合放在项目 README 顶部的徽章及其使用方式克隆模板时可以直接套用把示例中的模块引用替换为自己的项目Go Report Card用gofmt、go vet、gocyclo、golint、ineffassign、license、misspell扫描代码生成健康度徽章GoDoc提供在线版 GoDoc 文档文档中已用删除线标注该方案处于过渡状态Pkg.go.devGo 发现与文档的新入口可通过其徽章生成工具创建徽章Release显示项目最新 release 版本号。十、总结按规模裁剪的落地清单把这个模板落到实际项目中可以按以下清单执行起步单个main.gogo.mod模块路径首段带点兼容旧版本 Go代码开始分层可复用的公共代码进/pkg私有代码进/internal/cmd/app只留小main需要服务化接口契约进/api前端组件进/web配置模板进/configssystemd/supervisord 单元进/init需要构建与部署脚本进/scripts根 Makefile 保持一行注释级别的精简打包与 CI 进/build/package与/build/ci编排模板进/deployments开源或被依赖用/internal明确私有边界/examples提供使用示例/docs补充设计与用户文档README 加上质量徽章始终回避项目级/src。再次强调文档的核心立场这个布局是可裁剪的——克隆仓库、保留所需、删除其余它是一套“历史形成 社区增强”的目录语言而非必须逐条遵守的法条。理解每个目录的意图尤其是/internal的编译器强制语义比机械照搬目录树本身更有价值。参考仓库内相关文档README.md英文原版 / README_ru.md俄文版 / README_zh-CN.md简体中文版go.mod模块声明基准文件Makefile极简根级 Makefile 示范cmd/README.md、internal/README.md、pkg/README.mdapi/README.md、scripts/README.md、test/README.md、docs/README.md、website/README.md【免费下载链接】project-layoutStandard Go Project Layout项目地址: https://gitcode.com/GitHub_Trending/pr/project-layout创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考