本文永久链接 – https://tonybai.com/2022/09/25/the-tao-of-go

近期阅读了John Arundel的文章《The Tao of Go》，看完后我都有心去阅读一遍《道德经》了:)。作者将Go语言设计哲学与惯例与“道”学三宝有机的联系到一起，给了我不小的启发。这里译成中文，供大家参考。

你可以让水牛去任何地方，只要它们想去 – 杰拉尔德・温伯格 《咨询的奥秘》(译注：原文似乎将Gerald M. Weinberg 写成了Jerry Weinberg，应该是笔误)

“道”是指事物的内在本质或自然趋势。例如，水向低处流：这就是水的“道”。你可以筑坝、疏导、抽水，或以其他方式干扰它，但尽管你做了种种努力，它最终可能还是会流向它要去的地方。

你遵循“道”并将其作为你的处事原则，就是要对事物的自然趋势保持敏感，不浪费精力与之抗争，而是顺势而为，而非逆势而为。

扩展一下水的比喻，一个泳技糟糕的游泳者在水中乱扑腾，制造了很多噪音和骚动，但却没有真正前进。而道家，则是在水中冲浪(译注：借助波浪，顺势而为)。

那么什么是Go语言之道呢？如果我们以一种敏感的、聪明的方式来进行Go的软件开发，遵循语言和问题的自然轮廓，而不是试图用推土机把它们推开，那会是什么样子呢？让我们试着建立一些一般原则。

一. 仁慈(Kindness)

我有三宝，持而保之。一曰慈(kindness)，二曰俭(simplicity)，三曰不敢为天下先(humility，谦逊)。- 《道德经》

用仁慈(译注：最大程度的善意)和同情心编写程序是什么意思呢？它意味着我们为人而不是为计算机写代码。人容易犯错，没有耐心，缺乏经验，注意力不集中，而且在其他方面也不完美。我们可以通过在Go代码的设计和细节上花些心思，使大家的生活（和工作）变得更加轻松。

我们可以善待我们的用户：给我们的库起一个描述性的名字(译注：比如像net、os这样的名字)，让它们容易导入，提供良好的文档，并为它们提供宽松的开源许可。我们可以设计深度抽象，让用户利用小而简单的API来访问强大而有用的行为。

我们可以善待那些运行我们程序的人，使他们易于安装和更新，要求最少的配置和依赖，捕捉最常见的使用错误和运行时的错误，给用户提供有用的、准确的和友好的信息，告诉他们出现了什么错误以及如何解决。

聪明是一种天赋，仁慈是一种选择。 – 杰夫・贝佐斯

我们可以通过尽可能的清晰(clear)、简单(simple)和明确(explicit)来善待那些不得不阅读我们代码的人。我们可以给类型和函数起一个在上下文中有意义的名字，让用户用我们的抽象概念在直接的、逻辑的组合中创建自己的程序。我们可以通过遵守惯例、实现标准接口和以明显的方式做明显的事情来消除认知上的障碍和速度上的障碍。

在代码审查中，我们保持温和并多用鼓励性的语言。我们在别人的工作中找到值得称赞的地方，我们不会因为别人犯错或忽略细节而把他们当成傻瓜。如果我们对自己坦诚，我们会承认我们也会犯同样的错误。我们也知道，接受批评对我们来说是痛苦和困难的，但我们可以用仁慈来调节以应对对自己的批评。

最后，我们也要对自己仁慈，通过编写优秀的测试，使我们的程序在未来容易理解、修正和改进，当我们发现错误或设计缺陷时，不要对自己生气。

一旦代码仓库变成了意大利面条，就几乎不可能修复。 – John Ousterhout, 《软件设计的哲学》

另一个对我们未来的自己和我们的继任者仁慈的方法是，对程序的结构和整体设计进行小的、持续的改进。好的程序能活很久（当然，有一些糟糕的程序也能活很久），许多小改动的累积效应通常会使代码库变得混乱、复杂和笨拙。我们可以花一点额外的时间来帮助避免这种情况的发生，每当我们为某些事情访问代码库时，我们就可以重构和清理它。因为我们很少有机会从头开始重写系统，所以长期投入少量时间进行微改进是保持系统健康的唯一实用方法。

二. 简单(Simplicity)

“道”教给我们的第二种美德是节俭(frugality)、谦虚(modesty)、简单(simplicity)：以小博大，消除杂乱。Go本身就是一种“节俭”的语言，拥有较少的语法和表面积(译注：可能是较少的API的意思)。它并不试图做所有的事情，或者取悦所有人。

我们的生活被琐碎的细节浪费掉了。简化，再简化”— 亨利・大卫・梭罗《瓦尔登湖》

我们也应该这样做，使我们的程序小而聚焦，不混乱，做好一件事。深度抽象为强大的机器提供了一个简单的接口。我们不会让用户为了获得调用我们库的特权而做大量的文书工作。只要我们能够为最常见的情况提供一个简单的API和合理的默认值，我们就会这么做。

灵活性是一件好事，但我们不应该试图处理每一种情况，或提供每一种功能。可扩展性是很好的，但我们不应该为了我们目前还不需要的东西做出妥协而损害一个简单的设计。事实上，一个简单的程序比一个复杂的程序更容易扩展。

我有最简单的口味。我总是对最好的东西感到满意。 – 奥斯卡-王尔德，引自Edgar Saltus，”奥斯卡-王尔德，一个闲人的印象”

我们不会用函数、类型、接口、回调、参数和功能选项(options)来压垮用户。最小的API是最好的，因为它需要最少的知识来使用。我们不会用几十个包和子文件夹的子文件夹来将我们的module复杂化。我们不会采用无休止的命令行标志或要求用户编写冗长的配置文件。

我们满足于重复大块的代码，而不是纯粹为了满足我们保持代码不重复的愿望而发明不必要的抽象概念。如果我们可以通过为几种不同的类型实现相同的函数来解决问题，我们就不写复杂的代码生成器或泛型函数(译注：Go 1.18泛型落地后，有些时候使用泛型函数感官上代码更为简洁)。如果一个方法自然有点长，我们会让它长，而不是积极地把它重构为不必要的子函数，只是为了让每个子函数都能有几行长。

如果一个就够了，我们就不写十个测试。如果只需要一个函数，我们就不创建一个接口。我们不要让用户实现我们的接口，而是要实现他们的接口。

谁能出不由户，何莫由斯道也? – 孔子

我们是明确的/显式的(explicit)；我们避免魔法。我们不在没有帮助的地方使用并发性。我们让包自成一体，与其他包解耦，我们避免让一个包或API的类型泄漏到我们代码库的其他部分。我们设定明显的内部和外部界限，并加以执行。

我们节约资源；我们避免泄漏，并在必要时使用尽可能少的内存或CPU。我们高效地处理数据流，而不是将其放入大块的内存中。我们产生的垃圾越少，需要收集的就越少。我们不在不需要的地方传递Context。

我们不纠结于性能问题。Go是高性能的。但我们的代码可能不需要这么快；至少，不需要以牺牲简单性为代价来换取高性能。

正如Go谚语所说：我们接受接口值。这样我们就需要对它们是什么做出最少的假设，但我们会返回具体的值（结构），这样用户就不用为它们编写大量的类型断言。

三. 谦逊(Humility)

第三件宝物是谦逊。像水一样，道家寻求低调，不争，不比，不试图打动别人。Go本身是谦逊和务实的：它没有其他语言的所拥有高科技功能特性和理论优势。事实上，它故意忽略了许多其他语言的重要卖点。它的设计者对创造一种令人印象深刻的编程语言或在人气调查中名列前茅并不感兴趣，而是想为人们提供一种小型而简单的工具，以最实用和最直接的方式完成有用的工作。

Go认识到我们很容易犯错，因此它提供了很多方法来保护我们不犯错。它负责分配内存，清理我们已经用完的东西，并警告我们有未使用的包导入或变量。它是为那些知道自己不是什么都懂，并且了解自己的错误倾向的人(换句话说，是谦虚的人)设计的语言。

最危险的错误是没有认识到我们自己的错误倾向。 – 巴塞尔-利德尔-哈特

作为Go程序员，我们写代码不要显得过于聪明，我们通过这种方式来保持谦逊。我们写代码并不是为了给大家留下我们是多么了不起的程序员的印象：相反，我们满足于做明显的事情。我们清楚而直截了当地表达自己，而不觉得有必要把自己的个性强加在代码中。

当标准库能解决问题时，我们就使用它，而只有在它不能解决问题时才使用第三方库。如果有一个堪称事实标准的包，我们就使用它：如果它对别人足够好，对我们也足够好。

我们避免通过panic或调用os.Exit或log.Fatal来意外地终止用户的程序，因为我们认识到，我们没有足够的智慧来事先确定问题是否真的是致命的。相反，我们会在问题发生时处理一切可以处理的事情，而当我们不能处理时，我们会谦逊地返回一个错误，并提供有用的上下文信息，让我们的用户来决定如何处理。

我们可以认识到，我们并不了解所有的事情，我们也无法做出非常准确的预测（尤其是对未来的预测），所以我们不应该浪费时间和精力来预先设计我们可能永远不需要的东西。我们不认为我们最了解其他的软件是否会想和我们的软件一起使用，所以我们不会硬性规定对它的依赖。

我们假设我们写的任何东西都会包含bug，所以我们写了详尽的测试代码，试图引出意外的行为或不正确的结果。我们明白不可避免地会有一些我们不知道或无法正确预测的重要事情，所以我们不会为了现状而过多地优化代码，因为很多工作最终都会被浪费掉。

以学生的姿态（不断学习），永远不要觉得已经长大而不问问题，永远不要觉得知道得太多而拒绝学习新事物。- 奥格·曼狄诺, 《世界上最伟大的销售员》的作者

当我们审查别人的代码时，我们不会自动假设我们是最了解的：我们很乐意向任何有东西可以教我们的人学习。如果有些东西看起来很奇怪或不对，我们就会问：”从什么角度看这是有意义的？我没有什么信息可以解释为什么这是必要的？”

我们把我们的评论当作问题，以真诚而不是讽刺的方式提出：这有必要吗？如果……会怎样？你有没有考虑过……？如果……会不会更好？我们尊重别人的时间，就像尊重自己的时间一样，所以我们不要求他们提供不必要的信息，或者只为了符合我们喜欢的风格而做出微小的改变，或者坐在走形式的会议中浪费时间，或者写多余的状态报告。

我们知道我们并不总是正确的。明智的人可以以一种文明和建设性的方式对事情提出异议。如果我们把人们当做白痴，那么当他们反应不好的时候就不应该感到惊讶。相反，我们一开始就假设对方是理性的、体面的，并根据他们对情况的最佳理解，真诚地行事。有时情况并非如此，但这仍然是正确的默认假设，直到他们最终证明不是这样。

在要求别人审查自己的代码之前，我们会谦虚地审查自己的代码，因为如果我们这都懒得做，他们为什么要做？我们花时间逐行阅读，像一个新的用户或开发者那样阅读，遵循逻辑逐一论证：从哪里开始阅读是否很清楚？程序是否在一开始就引入了关键的类型或常量并说明它们是如何使用的？命名是否清楚并准确地指明了它们的作用，或者它们在十几次重构中是否变得混乱和过时了？程序是否整齐自然地融入了它的结构，或者它在某些部分过度堆砌，而在其他部分奇怪地留下了空白？

因为我们没有被自己的聪明和优雅所束缚，我们不需要把三四个不同的想法塞进一行代码中。相反，我们把逻辑清晰、简单、显式地列出，一步一步地，一个一个地陈述，一点一点地，以读者所期望的方式准确地做必要的事情。在无法做到这一点的地方，我们会不厌其烦地向读者解释他们需要知道什么才能理解发生了什么。

因为我们知道我们不是天才，我们不可能把程序写得那么出色，不言自明，所以我们在解释上花了一些功夫。我们为代码提供文档，不仅说明程序的作用，而且说明如何用它完成用户可能想要做的事情。文档还包含了详细的使用例子，准确地显示出需要做什么，从头开始，以执行现实的任务，当它完成时，用户应该期望看到什么，以及他们接下来应该做什么，并且我们严格地定期检查这些例子，以确保它们仍然有效。

四. 无为(Not Striving)

我们已经谈到了一些将仁慈、简单和谦逊这三件宝物应用于用Go编写软件的方法。这些品质已经存在于每个人身上，即使它们在一些人身上隐藏得很好。同样地，每个人都已经知道如何在编程和生活中遵循“道”。的确，他们不能不这样做。但是，一旦你理解了这个事实，并停止在所有事情上做这样的挣扎，生活就会变得更加有趣。

道给我们的最后一个教导是无为（not striving）。这有时会被误解为懒惰、退缩或被动；恰恰相反。努力工作并不总是意味着工作出色。我们都知道那些长期忙碌的人，总是匆匆忙忙，手忙脚乱，活动频繁，但他们似乎从未真正取得过什么成就。而且，他们过得很痛苦，因为他们也知道这一点。

相反，我们经常在别人看来我们什么都没做的时候以最佳状态完成我们的工作：在一个美丽的日子里在河边散步，或者坐在门廊上看蜘蛛结网。如果我们能聪明地从忙碌中停下来，只需一分钟，正确的想法往往就会直接出现在我们的头脑中。

与其把每个问题都当作要攻击的敌人、要攀登的山峰或要拆毁的墙壁，我们可以使用“无为”原则（有时“不强迫(not forcing)”会是更好的翻译）。我们可能都有过这样的尴尬经历：无果地推一扇顽固的门，最后才意识到这扇门对拉动的反应更好。在我们的日常工作中，我们忽略了哪些小迹象表明我们应该拉而不是推？

解决问题的心态是好的，但消除问题则更好。我们怎样才能重新规划这个问题，使其消失？对需求的重述会使解决方案变得微不足道，甚至显而易见？是否有一个简单而优雅的设计是我们没有看到的，因为我们专注于一些被证明是不相关的细节？我们是否可以不用尝试解决这个问题？最好的优化是根本不做这件事。

把编程和打字混为一谈是一个常见的错误。如果有人只是坐在那里盯着空间，那就不像是在做什么有用的事情。但是，如果他们在键盘上疯狂地敲击，我们就会认为他们在做什么。事实上，真正的编程发生在打字之前，有时甚至代替了打字。当我们构思了一段非常好的程序，我们唯一需要按的键往往是删除键。

真正有趣的是，你不需要相信我的话来证明道家原则在编程中的有效性，或者在生活的其他领域。世界本身会教你什么是有效的，什么是无效的，以及如何分辨它们。在行使你的仁慈、简单和谦逊方面做一些小实验，看看会发生什么，感觉如何。

你不必称它为“道”，如果这让你感到恼火。这只是一个人为编造的词。如果你一直知道做事情有正确的方法和错误的方法，而且你认为我只是用了一个花哨的中文名字而没有说什么新的或有价值的东西，你是对的。

下次你遇到问题时，试一次不努力或不强迫，看看是否可以温和地鼓励问题自己解决。如果你发现自己在努力把水牛送到你想去的地方，就不要再挣扎了。问问自己，你是否能找到水牛想去的地方，也许那可能不是它的最佳位置。

“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群！高品质首发Go技术文章，“三天”首发阅读权，每年两期Go语言发展现状分析，每天提前1小时阅读到新鲜的Gopher日报，网课、技术专栏、图书内容前瞻，六小时内必答保证等满足你关于Go语言生态的所有需求！2022年，Gopher部落全面改版，将持续分享Go语言与Go应用领域的知识、技巧与实践，并增加诸多互动形式。欢迎大家加入！

我爱发短信：企业级短信平台定制开发专家 https://tonybai.com/。smspush : 可部署在企业内部的定制化短信平台，三网覆盖，不惧大并发接入，可定制扩展； 短信内容你来定，不再受约束, 接口丰富，支持长短信，签名可选。2020年4月8日，中国三大电信运营商联合发布《5G消息白皮书》，51短信平台也会全新升级到“51商用消息平台”，全面支持5G RCS消息。

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式：

• 微博：https://weibo.com/bigwhite20xx
• 博客：tonybai.com
• github: https://github.com/bigwhite

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

本文永久链接 – https://tonybai.com/2022/04/28/the-standard-layout-of-go-project

每当我们编写一个非hello world的实用Go程序或库时，我们都会在项目结构、代码风格以及标识符命名这三个“门槛”前面踯躅徘徊许久，甚至始终得不到满意答案。

本文将通过《Go语言精进之路：从新手到高手的编程思想、方法与技巧》这本书的内容来详细看一看Go项目结构这道“门槛”应该如何迈过，以帮助大家能更快地深入Go语言的核心腹地，提高学习效率。

除非是像hello world这样的简单程序，但凡我们编写一些实用程序或库，我们都会遇到采用什么样的项目结构（project structure）的问题（通常一个Go项目对应一个仓库repository）。在Go语言中，项目结构的同样十分重要，因为这决定了项目内部包的布局以及包依赖关系是否合理，同时还会影响到外部项目对该项目中包的依赖与引用。

1. Go项目的项目结构

我们先来看看世界上第一个Go项目- Go语言自身的项目结构是什么样的。

Go项目的项目结构自1.0版本发布以来一直十分稳定，直到现在Go项目的顶层结构基本没有大的改变。截至go项目commit 1e3ffb0c（2019.5.14），go项目结构如下：

$ tree -LF 1 ~/go/src/github.com/golang/go
./go
├── api/
├── AUTHORS
├── CONTRIBUTING.md
├── CONTRIBUTORS
├── doc/
├── favicon.ico
├── lib/
├── LICENSE
├── misc/
├── PATENTS
├── README.md
├── robots.txt
├── src/
└── test/

作为Go语言的“创世项目”，其项目结构的布局对后续的其他Go语言项目具有重要的参考意义，尤其是早期Go项目中src目录下面的结构，更是在后续被Go社区作为Go应用项目结构的模板被广泛使用。我们以早期的Go 1.3版本的src目录下的结构为例：

$ tree -LF 1 ./src
./src
├── all.bash*
├── all.bat
├── all.rc*
├── clean.bash*
├── clean.bat
├── clean.rc*
├── cmd/
├── lib9/
├── libbio/
├── liblink/
├── make.bash*
├── make.bat
├── Make.dist
├── make.rc*
├── nacltest.bash*
├── pkg/
├── race.bash*
├── race.bat
├── run.bash*
├── run.bat
├── run.rc*
└── sudo.bash*

关于上面src目录下面的结构，我总结了三个特点：

1）代码构建的脚本源文件放在src下面的顶层目录下；
2）src下的二级目录cmd下面存放着go工具链相关的可执行文件（比如：go、gofmt等）的主目录以及它们的main包源文件；

$ tree -LF 1 ./cmd
./cmd
...
├── 6a/
├── 6c/
├── 6g/
...
├── cc/
├── cgo/
├── dist/
├── fix/
├── gc/
├── go/
├── gofmt/
├── ld/
├── nm/
├── objdump/
├── pack/
└── yacc/

3）src下的二级目录pkg下面存放着上面cmd下各工具链程序依赖的包、go运行时以及go标准库的源文件

$ tree -LF 1 ./pkg
./pkg
...
├── flag/
├── fmt/
├── go/
├── io/
├── log/
├── math/
...
├── syscall/
├── testing/
├── text/
├── time/
├── unicode/
└── unsafe/

在Go 1.3版本以后至今，Go项目下的src目录中发生了几次结构上的变动：

• Go 1.4版本中删除了Go源码树中src/pkg/xxx中pkg这一层级目录而直接使用src/xxx；
• Go 1.4版本在src下面增加internal目录，用于存放无法被外部导入仅Go项目自用的包；

• Go 1.6版本在src下面增加vendor目录，但Go项目自身真正启用vendor机制是在Go 1.7版本中。vendor目录中存放了go项目自身对外部项目的依赖，主要是golang.org/x下的各个包，包括：net、text、crypto等。该目录下的包会在每次Go版本发布时做更新；

• Go 1.13版本在src下面增加了go.mod和go.num，实现了go项目自身的go module迁移，go项目内所有包被放入名为std的module下面，其依赖的包依然是golang.org/x下的各个包

// Go 1.13版本go项目src下面的go.mod
module std

go 1.12

require (
    golang.org/x/crypto v0.0.0-20200124225646-8b5121be2f68
    golang.org/x/net v0.0.0-20190813141303-74dc4d7220e7
    golang.org/x/sys v0.0.0-20190529130038-5219a1e1c5f8 // indirect
    golang.org/x/text v0.3.2 // indirect
)

下面是最新的Go 1.16版本src目录下的完整布局：

├── Make.dist
├── README.vendor
├── all.bash*
├── all.bat
├── all.rc*
├── bootstrap.bash*
├── buildall.bash*
├── clean.bash*
├── clean.bat
├── clean.rc*
├── cmd/
├── cmp.bash
├── go.mod
├── go.sum
├── internal/
├── make.bash*
├── make.bat
├── make.rc*
├── race.bash*
├── race.bat
├── run.bash*
├── run.bat
├── run.rc*
├── testdata/
...
└── vendor/

2. Go语言典型项目结构

（1）Go项目结构的最小标准布局

关于Go应用项目结构的标准布局是什么样子的，Go官方团队始终没有给出参考标准。不过作为Go语言项目的技术负责人，Russ Cox在一个开源项目的issue中给出了他关于Go项目结构的最小标准布局Russ Cox关于Go项目结构的最小标准布局的想法的想法。他认为的Go项目的最小标准布局应该是如下这样的：

// 在Go项目仓库根路径下

- go.mod
- LICENSE
- xx.go
- yy.go
...

或

- go.mod
- LICENSE
- package1
  - package1.go
- package2
  - package2.go
...

至于pkg、cmd、docs这些目录不应该成为Go项目标准结构的一部分，至少不是必须的。笔者认为Russ Cox给出的最小标准布局与Go一贯崇尚的“简单”哲学是一脉相承的，这个布局很灵活，可以满足各种Go项目的需求。

但是在Russ Cox阐述上述最小标准之前，Go社区其实是处于“无标准”状态的，早期Go语言自身项目的结构布局对现存的大量Go开源项目的影响依然持久，对于一些规模稍大些的Go应用项目，我们势必会在上述的“最小标准布局”的基础上做出扩展。而这种扩展也显然也不会是盲目的，而还是会参考Go语言项目自身的结构布局，于是我们就有了下面的非官方标准的建议结构布局。

（2）以构建二进制可执行文件为目的的Go项目结构

基于Go语言项目自身的早期结构以及后续演进，Go社区在多年的Go语言实践积累后逐渐形成了一种典型项目结构，这种结构与Russ Cox的最小标准布局是兼容的，如图1所示。

上面就是一个支持构建二进制可执行文件（在cmd下）的典型Go项目的结构，我们分别来看一下各个重要目录的用途：

• cmd目录：存放项目要编译构建的可执行文件对应的main包的源文件。如果有多个可执行文件需要构建，每个可执行文件的main包单独放在一个子目录中，比如图中的app1、app2；cmd目录下的各app的main包将整个项目的依赖连接在一起；并且通常来说，main包应该很简洁。我们在main包中会做一些命令行参数解析、资源初始化、日志设施初始化、数据库连接初始化等工作，之后就会将程序的执行权限交给更高级的执行控制对象；也有一些go项目将cmd这个名字改为app，但其功用并没有变；

• pkg目录：存放项目自身要使用、同样也是可执行文件对应main包所要依赖的库文件；同时该目录下的包还可以被外部项目引用，算是项目导出包的一个“聚合”；也有些项目将pkg这个名字改为lib，但目录用途不变；由于Go语言项目自身在1.4版本中去掉了pkg这一层目录，因此也有一些项目直接将包平铺到项目根路径下，但笔者认为对于一些规模稍大的项目，过多的包会让项目顶层目录不再简洁，显得很“拥挤”，因此我个人建议对于复杂的Go项目，保留pkg目录未尝不可。

• Makefile：这里的Makefile是项目构建工具所用脚本的“代表”，它可以代表任何第三方构建工具所用的脚本。Go并没有内置如make、bazel等级别的项目构建工具，对于一些规模稍大的项目而言，项目构建工具似乎还不可缺少。在Go典型项目中，项目构建工具的脚本一般放在项目顶层目录下，比如这里的Makefile；对于构建脚本较多的项目，也可以建立build目录，并将构建脚本的规则属性文件、子构建脚本放入其中。

• go.mod和go.sum：Go语言包依赖管理使用的配置文件。Go 1.11版本引入go modules机制，Go 1.16版本中，go module成为默认的依赖包管理和构建机制。因此对于新的Go项目，我们建议基于go modules进行包依赖管理。对于没有使用go modules进行包管理的项目（可能主要是一些使用go 1.11以前版本的go项目），这里可以换为dep的Gopkg.toml和Gopkg.lock或者glide的glide.yaml和glide.lock等。

• vendor目录（可选）：vendor是Go 1.5版本引入的用于在项目本地缓存特定版本依赖包的机制，在go modules机制引入前，基于vendor可以实现可重现的构建（reproducible build），保证基于同一源码构建出的可执行程序是等价的。go modules本身就可以实现可重现的构建，而无需vendor，当然go module机制也保留了vendor目录（通过go mod vendor可以生成vendor下的依赖包；通过go build -mod=vendor可以实现基于vendor的构建），因此这里将vendor目录视为一个可选目录。一般我们仅保留项目根目录下的vendor目录，否则会造成不必要的依赖选择的复杂性。

Go 1.11引入的module是一组同属于一个版本管理单元的包的集合。并且Go支持在一个项目/仓库中存在多个module，但这种管理方式可能要比一定比例的代码重复引入更多的复杂性。因此，如果项目结构中存在版本管理的“分歧”，比如：app1和app2的发布版本并不总是同步的，那么笔者建议将项目拆分为多个项目（仓库），每个项目单独作为一个module进行单独的版本管理和演进。

（3）以只构建库为目的的Go项目结构

Go 1.4发布时，Go语言项目自身去掉了src下的pkg这一层目录，这个结构上的改变对那些以只构建库为目的的Go库类型项目结构有着一定的影响。我们来看一个典型的Go语言库类型项目的结构布局，见图2。

我们看到库类型项目结构与Go项目的最小标准布局也是兼容的，但相比于以构建二进制可执行文件为目的的Go项目要简单一些：

• 去除了cmd和pkg两个子目录：由于仅构件库，没必要保留存放二进制文件main包源文件的cmd目录；由于Go库项目的初衷一般都是为了对外部（开源或组织内部公开）暴露API，因此也没有必要将其单独聚合到pkg目录下面了；

• vendor也不再是可选目录：对于库类型项目而言，我们不推荐在项目中放置vendor目录去缓存库自身的第三方依赖，库项目仅通过go.mod（或其他包依赖管理工具的manifest文件）明确表述出该项目依赖的模块或包以及版本要求即可。

（4）关于internal目录

无论是上面哪种类型的Go项目，对于不想暴露给外部引用，仅限项目内部使用的包，在项目结构上可以通过Go 1.4版本中引入的internal包机制来实现。以库项目为例，最简单的方式就是在顶层加入一个internal目录，将不想暴露到外部的包都放在该目录下，比如下面项目结构中的ilib1、ilib2：

// 带internal的Go库项目结构
$tree -F ./chapter2/sources/GoLibProj
GoLibProj
├── LICENSE
├── Makefile
├── README.md
├── go.mod
├── internal/
│   ├── ilib1/
│   └── ilib2/
├── lib.go
├── lib1/
│   └── lib1.go
└── lib2/
    └── lib2.go

这样，根据go internal机制的作用原理，internal目录下的ilib1、ilib2可以被以GoLibProj目录为根目录的其他目录下的代码(比如lib.go、lib1/lib1.go等）所导入和使用，但是却不可以为GoLibProj目录以外的代码所使用，从而实现选择性的暴露API包。当然internal也可以放在项目结构中的任一目录层级中，关键是项目结构设计人员明确哪些要暴露到外层代码，哪些仅用于同级目录或子目录中。

对于以构建二进制可执行文件类型为目的的项目来说，我们同样可以将不想暴露给外面的包聚合到项目顶层路径下的internal下，与暴露给外部的包的聚合目录pkg遥相呼应。

3. 小结

本文详细介绍了Go语言项目的结构布局的来龙去脉以及Go项目结构的事实标准。文中的两个针对构建二进制可执行文件类型以及库类型的项目参考结构是Go社区在多年实践后得到公认且使用较为广泛的项目结构，并且它们与Russ Cox提出的Go项目最小标准布局是兼容的，对于稍大型的Go项目来说很具有参考价值。但它们也不是必须的，在Go语言早期，很多项目将所有源文件都放在位于项目根目录下的根包中的做法在一些小规模项目中同样工作得很好。

对于以构建二进制可执行文件类型为目的的项目来说，受Go 1.4项目结构影响，将pkg这一层次目录去掉也是很多项目选择的结构布局方式。

上述的参考项目结构与产品设计开发领域的“最小可行产品”（minimum viable product，简称为mvp）的思路有些异曲同工，开发者可以在这样一个最小的“项目结构核心”的基础上根据实际需要对其进行扩展。

如果您想要了解更多有关Go项目结构与布局的内容，推荐您详细阅读我的新作《Go语言精进之路：从新手到高手的编程思想、方法与技巧》。

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式：

• 微博：https://weibo.com/bigwhite20xx
• 微信公众号：iamtonybai
• 博客：tonybai.com
• github: https://github.com/bigwhite
• “Gopher部落”知识星球：https://public.zsxq.com/groups/51284458844544

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。