本文翻译自Go社区知名Gopher和博主Dave Cheney的文章《The Zen of Go》。

本文来自我在GopherCon Israel 2020上的演讲。文章很长:) 如果您希望阅读精简版，请移步到the-zen-of-go.netlify.com。

该演讲视频还未上线。如上线，我会把它更新到本文中的。

我应该如何编写出好代码？

我最近一直在思考很多事情，每当反思自己的工作成果时，眼前常会出现一行字幕：我该如何编写出好代码？ 主观上，没人愿意去编写糟糕的代码，那么问题来了：你是怎么知道你编写出好的Go代码了呢？

如果好与坏之间存在连续性，那么我们怎么知道哪些是好的部分？它的特性、属性、标志、模式和惯用法又是什么呢？

Go语言惯用法(idiomatic Go)

这让我走进Go惯用法。说某种东西是惯用的，就是说它遵循了时代的风格。如果某些东西不是惯用的，那它没有遵循流行的风格，感觉不时髦。

更重要的是，对某人说他们的代码不复合惯用法并不能解释为什么这些代码不符合惯用法。为什么会这样？像所有真相一样，答案可以在词典中找到：

idiom (noun): a group of words established by usage as having a meaning not deducible from those of the individual words.
惯用法（名词）：一组由用法确定的且其含义无法从单个单词的含义中推导出来的单词。

惯用法是共享价值观(value)的标志。Go惯用法不是您从书本中学到的东西，而是通过成为社区的一部分而获得的。

Go惯用法字样用多了，便形成了“口头禅”，这引起我的担忧：这种口头禅在许多方面它可能是具有排他性的。比如：有人说“你不能和我们坐在一起。” 但毕竟这不是我们批评某人的代码不符合惯用法时的索要表达的意思，是吧？他们只是没有做对，看起来不对，它没有遵循流行的风格而已。

我认为Go惯用法不是教如何编写好的Go代码的合适机制，因为从根本上说，它仍然告诉某人做错了(译注：这容易引起对方反感)。如果在他们最愿意接受建议的时候，我们给出让他们不感觉疏远的建议是否会更好些？

谚语(Proverbs)

摆脱有问题的惯用法，Gopher们还有哪些其他的文化手工艺品吗？也许我们可以转向Rob Pike精彩的Go 谚语。这些谚语是合适的教学工具吗？它们会告诉Go新手如何编写好的Go代码吗？

总的来说，我不这么认为。这并不是要驳斥Rob Pike的作品。只是像濑越宪作（Segoe Kensaku）的原著一样，Go谚语只是观察，而不是价值观的陈述。我们再次搬出字典：

proverb (noun): a short, well-known pithy saying, stating a general truth or piece of advice.
谚语（名词）：简短而众所周知的俗语，陈述一般的真理或一段忠告。

Go Proverbs的目的是揭示有关语言设计的更深层次的真理，但是像empty interface says nothing这样的建议对于一个来自商没有结构化类型的语言的新手来说有什么用呢？

重要的是要认识到，在一个不断发展的社区中，任何时候学习Go语言的人的数量都远超过那些声称掌握了该语言的人的数量。因此，在这种情况下，谚语可能也不是最佳的教学工具。

工程价值观

丹·卢（Dan Luu）找到了马克·卢科夫斯基（Mark Lucovsky）关于Windows团队在Windows NT-Windows 2000开发阶段时的工程文化的演讲。我之所以提到它，是因为卢科夫斯基将一种文化描述为一种评估设计和权衡取舍的常用方法。

讨论文化的方法有很多，但是就工程文化而言，Lucovsky的描述是恰当的。其中心思想是在未知的设计空间中用价值观指导决策。Windows NT团队的价值观是：可移植性，可靠性，安全性和可扩展性。粗略地说工程价值观就是在这里完成工作的方式。

Go的价值观

Go的显式价值观是什么呢？定义Go程序员解释世界方式的核心信念或哲学又是什么？他们如何发布宣传？他们怎么传授？如何执行？它们又是如何随着时间变化的？

作为新Go程序员，您将如何被灌输Go的工程价值观？或者，你是一位经验丰富的Go专家，你如何将你的价值观传播给“下一代”？就像我们知道的那样，知识传递的过程不是一个可选项。没有新的血液和新的观念，我们的社区将变得短视和枯萎。

其他语言的价值观

为了给我所要了解的场景做铺垫，我们可以先看看其他语言，我们看看它们的工程价值观。

例如，C++（包括其扩展：Rust）认为程序员不必为自己不使用的特性付费。如果程序未使用该语言的某些计算成本昂贵的特性，则不应强迫该程序承担该特性的成本。该价值观从语言扩展到其标准库，并用作判断所有用C++编写的代码设计的标准。

在Java，Ruby和Smalltalk中，一切都是对象的核心价值观驱动着围绕着消息传递，信息隐藏和多态的程序设计风格。在程序中采用过程式或函数式设计风格会被认为是错误的，或者按照Gophers的说法，是不符合惯用法的。

回到我们自己的Go社区，烙印在Go程序员心中的工程价值观是什么呢？在我们社区中的讨论是很容易引战的，因此要从第一条原则衍生出一套价值观念将是一个巨大的挑战。共识很关键，但随着讨论贡献者数量的增加，难度就成倍增加。但是，如果有人已经为我们完成了这些艰苦的工作了呢？

~~Python~~ Go之禅

几十年前，蒂姆·彼得斯（Tim Peters）坐下来写下了PEN-20（Python之禅）。Peters试图记录他认为Guido van Rossum(Python之父)在Python社区扮演的BDFL(仁慈的独裁者)角色时所应用的工程价值观。

在本文的剩余部分中，我将着眼于Python之禅，并问问大家：是否有什么可以用来揭秘Go程序员的工程价值观的？

一个好的package始于一个好名字

让我们从香辛的东西开始

“Namespaces are one honking great idea–let’s do more of those!” The Zen of Python, Item 19
“命名空间是一个很棒的主意-让我们多做些吧！” Python之禅，条款19

这是相当明确的，Python程序员应该使用命名空间，多多益善。

package就是Go语言的命名空间。我怀疑是否有人质疑将组件分组到程序包中利好设计和潜在重用。但关于这么做的正确方法的困惑肯定会有的，尤其是你拥有另一门语言10年的使用经验。

在Go中，每个程序包都应有一个目的/用途，而了解程序包目的/用途的最佳方法是通过其名字-一个名词。包的名字描述了它提供的内容。因此，这里重新解释一下Peters的话：每个Go软件包(package)都应该仅有一个单一的目的/用途。

这不是一个新主意，我已经说了一段时间了，但是为什么要这样做而不是使用将软件包用于细粒度分类的方法呢？为什么，因为变化(change)。

“Design is the art of arranging code to work today, and be changeable forever.” - Sandi Metz
“设计是安排代码以使其至今天仍然可以工作并且永远可以更改的艺术。” - 桑迪·梅斯

变化是我们所从事的游戏的名称(译注：这里的游戏指代程序开发工作)。作为程序员，我们要做的就是管理变变化。当我们做得很好时，我们称之为设计或架构。当我们做得不好时，我们称其为技术债务或遗留代码。

如果你编写的程序对于一组固定的输入可以一次性地完美地工作，那么没人会在乎代码的好坏，因为最终程序的输出才是企业和业务所关心的。

但这是不正确的。软件具有缺陷(bug)，需求变更，输入变更，并且很少有程序被编写为仅执行一次，因此您的程序会随着时间而变化。可能是您要为此承担任务，更有可能是其他人，但是必须更改该代码。有人必须维护该代码。

那么，如何使程序更改变得容易呢？无所不在的接口？使一切变得易于mock？邪恶的依赖注入(译注：作者对DI似乎很排斥，用了带有感情色彩的词汇)？好吧，也许，对于某类程序，但不是很多，这些技术将很有用。但是，对于大多数程序而言，预先设计一些灵活的方法要比工程设计更为重要。

相反，如果我们采取的立场是取代组件而不是增强组件，该怎么办？知道何时需要更换某些物品的最佳方法是什么时候该物品没有按照锡盒/罐头盒上的说明进行操作。

一个好的包始于选择一个好的名字。把你的包名字想象成电梯游说（Elevator pitch，即用极具吸引力的方式简明扼要地阐述自己的观点）， 仅用一个词就可以描述包的内容。当名字不再符合要求时，请查找替代名字。

简单性很重要

“Simple is better than complex.” - The Zen of Python, Item 3
“简单胜于复杂。” - Python之禅，条款3

PEP-20说：简单胜于复杂，我完全同意。几年前，我发布了这条推文:

大多数编程语言开始都是为了简单，但最终只是为了功能强大而努力。— Dave Cheney（@davecheney）2014年12月2日

至少在当时，我的观察是，我想不出一生中使用的哪门语言不标榜着简单。每种新语言都为其固有的简单性提供了理由和诱因。但是，当我研究时，我发现简单性并不是与Go语言同时代的许多现代语言的核心价值观。也许这只是一个便宜的镜头¹，但是可能是这些语言不是很简单，或者它们不认为自己很简单。他们不认为简单是其核心价值观。

但是什么时候简单变得过时了？为什么商业软件开发行业会忘记这个基本原则？

“There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult.” - C. A. R. Hoare, The Emperor’s Old Clothes, 1980 Turing Award Lecture

“构建软件设计的方式有两种：一种方式是使其变得如此简单，以至于显然没有缺陷，另一种方式是使得它变得如此复杂以至于没有明显的缺陷。第一种方法要困难得多。” - CAR Hoare，皇帝的旧衣，1980年图灵奖演讲

我们知道：简单并不意味着容易。通常，使某些东西易于使用而不是易于构建需要更多的工作。

“Simplicity is prerequisite for reliability.” - Edsger W Dijkstra, EWD498, 18 June 1975
“简单性是可靠性的前提。”-  埃兹格·迪克斯特拉（Essger W Dijkstra），EWD498，1975年6月18日

我们为什么要追求简单？为什么Go程序简单很重要？简单并不意味着粗糙，它意味着可读性和可维护性。简单并不意味着“不复杂”，它意味着可靠，有共鸣且易于理解。

“Controlling complexity is the essence of computer programming.” - Brian W. Kernighan, Software Tools (1976)
“控制复杂性是计算机编程的本质。” - Brian W. Kernighan，软件工具  （1976）

Python是否遵守其简单性的说法尚有争议，但Go坚持将简单性作为核心价值观。我认为我们都可以认同，就Go而言，简单代码比聪明代码更可取。

避免包级别状态

“Explicit is better than implicit.” - The Zen of Python, Item 2
“显式胜于隐式。” - Python的禅宗，第2项

我认为彼得斯在这个地方的抱负胜于实际。Python中的许多内容并不明确；装饰器，dunder方法(译注：不知此为何物)等。毫无疑问，这些特性的功能强大，存在这些特性是有原因的。每个特性都是因某人非常关心的事情，尤其是复杂的特性。但是大量使用这些特性使读者很难预测操作的成本。

好消息是，像Go程序员一样，我们可以选择显式代码。显式可能意味着很多事情，也许您可能认为显式只是一种表达官僚主义和漫长风气的好方法，但这只是肤浅的解释。只关注页面的语法、烦恼行长和自制表达式是一种错误的说法。在我看来，更有价值的地方是与耦合和状态有关。

耦合(coupling)是衡量一件东西依赖另一件东西的数量的方法。如果两件事紧密结合，它们就会一起运动。影响其中一个事物的行为会直接反映在另一个事物中。想象一下，一列火车，每个车厢连在一起；发动机行驶到哪里，车厢就跟随到哪里。

描述耦合的另一种方法是内聚(cohesion)一词。内聚衡量两件事自然地在一起的程度。当我们进行一个内聚的争论，或者一个内聚的团队，它们的所有零件都可以自然装配在一起，就像设计的一样。

为什么耦合很重要？因为就像火车一样，当您需要更改一段代码时，与之紧密相关的所有代码都必须更改。一个再适合不过的例子：有人发布了他们的API的新版本，现在您的代码无法通过编译了。

API是不可避免的耦合源，但是存在更多隐蔽的耦合形式。显然，每个人都知道，如果API的原型发生更改，则该调用的传入和返回数据都会发生变化。就在函数原型中；我采用这些类型的值，并返回其他类型的值。但是，如果API以其他方式传递数据怎么办？如果每次调用此API的结果都是基于上次调用该API的结果，即使您没有更改参数该怎么办？

这是状态，状态管理是计算机科学中的问题。

package counter

var count int

func Increment(n int) int {
        count += n
        return count
}

假设我们有这个简单的counter包。您可以调用Increment以增加计数器，即便传入0，你也可以得到返回值。

假设您必须测试此代码，那么每次测试后如何重置计数器？假设您想并行运行这些测试，可以吗？现在，假设您要为每个程序进行不止一个计数，您可以这样做吗？

不，当然不行。显然，答案是将count变量封装为类型。

package counter

type Counter struct {
        count int
}

func (c *Counter) Increment(n int) int {
        c.count += n
        return c.count
}

现在想象一下，这个问题不局限于计数器，还包括应用程序的主要业务逻辑。您可以单独测试吗？您可以并行测试吗？您一次可以使用多个实例吗？如果回答那些问题为否，则原因是软件的包级别状态。

避免包级别状态。通过提供一种类型需要的依赖项作为该类型上的字段，而不是使用包变量，来减少耦合和怪异的行为。

为失败而计划，而不是成功而计划

“Errors should never pass silently.” - The Zen of Python, Item 10
“错误绝不能默默传递。” - Python之禅，条款10

有人说过，支持异常处理的语言遵循武士原则(Samurai principle)。要么全胜归来，要么(失败)全不回来。在基于异常的语言中，函数仅返回有效结果。如果他们没有成功，那么控制流程将采纳完全不同的路径。

未检查的异常显然是不安全的编程模型。当您不知道哪些语句可能引发异常时，如何在存在错误的情况下编写健壮的代码？Java尝试通过引入checked exception的概念来使异常更安全，据我所知，这种checked exception在另一种主流语言中没有被引入。有很多使用异常的语言，但是除了Java，所有语言都使用未经检查的各种异常(unchecked exception)。

显然，Go选择了不同的路径。Go程序员认为，健壮的程序是由处理失败情况的片段组成的，然后再处理happy path。在Go设计的空间中：服务器程序，多线程程序，处理网络输入的程序，如果要构建可靠的程序，那么处理意外数据、超时、连接失败和损坏的数据必须是程序员的首要任务。

“I think that error handling should be explicit, this should be a core value of the language.” - Peter Bourgon, GoTime #91
“我认为错误处理应该是显式的，这应该是语言的一个核心价值观。” - 彼得·布尔贡（Peter Bourgon），GoTime＃91

我想回应彼得的主张，因为这是本文的动力。我认为Go的成功很大程度上归功于显式的处理错误的方式。Go程序员首先考虑失败情况。我们首先解决如果...怎么办的情况。这导致程序在编写时处理故障，而不是在生产中处理故障。

反复出现的下面代码片段：

if err != nil {
    return err
}

所付出的成本已基本被在故障发生时刻意处理每个故障情况的价值超过了(译者注：上面的重复代码段也是利大于弊)。关键还在于显式处理每个错误的文化价值观。

早点返回，而不是深层嵌套

“Flat is better than nested.” - The Zen of Python, Item 5
“扁平比嵌套更好。” - Python的禅宗，条款5

这是一个明智的建议，而且它来自以缩进作为控制流主要形式的语言。我们如何用Go来解释这个建议呢？gofmt控制Go程序的整体风格(空白与缩进)，因此无需执行任何额外操作。

我之前写过关于package名字的文章，这里可能有一些建议：避免复杂的软件包层次结构。以我的经验，程序员越努力细分和分类Go代码库，他们越有可能陷入包导入循环的死角。

我认为第5项条款建议的最佳应用是函数内的控制流。简而言之，避免需要控制流缩进过深。

“Line of sight is a straight line along which an observer has unobstructed vision.” - May Ryer, "Code: Align the happy path to the left edge" https://medium.com/@matryer/line-of-sight-in-code-186dd7cdea88

“代码行展现给观察者的视觉效果应该是一条畅通的直线。- May Ryer， “代码：将快乐路径对齐到左边缘”

Mat Ryer将这种想法描述为视线编码(line of sight coding )。视线编码意味着：

• 如果不满足前提条件，则使用保护子句尽早返回。
• 将成功的return语句放在函数的末尾，而不是放在条件代码块中。
• 通过提取函数和方法来降低函数的整体缩进级别。

该建议的关键是您所关心的事情，功能所要做的事情永远不会有在屏幕右侧滑出视线的危险。这种风格有一个额外的副作用，您可以避免团队中对行长度的毫无意义的争论。

每次缩进时，都会向程序员堆栈添加另一个先决条件，从而消耗他们的7±2个短期内存插槽之一(译注：7±2指的是人类能短期记忆的事件数量大约是7，±2是个体差异)。将函数的成功执行路径贴近屏幕左手侧，不要深入嵌套。

如果你认为它性能差，请通过基准测试证明

“In the face of ambiguity, refuse the temptation to guess.” - The Zen of Python, Item 12
“面对模棱两可，拒绝猜测的诱惑。” - Python之禅，条款12

编程基于数学和逻辑，这两个概念很少涉及机会元素。但是，作为程序员，我们每天都在猜测许多事情。这个变量有什么作用？此参数有什么作用？如果我在这类传入nil会怎样？如果我调用Register两次会怎样？实际上，现代编程中存在很多猜测，尤其是在使用不是你编写的库时。

“APIs should be easy to use and hard to misuse.”  - Josh Bloch
“API应该易于使用并且不容易被滥用。” - 乔什·布洛赫（Josh Bloch）

我知道的帮助程序员避免猜测的最好方法之一是在构建API时，应专注于默认用例。使调用者尽可能轻松地执行最常见的事情。但是，我过去写过很多关于API设计的文章，所以我对第12项的解释是：不要猜测性能。

尽管您可能考虑到Knuth的建议，但Go语言成功的推动力之一是其高性能的执行。您可以在Go中编写高性能的程序，因此人们会因此选择Go。关于性能有很多误解，所以我的要求是，当您希望对代码进行性能调优时，或者遇到一些教条式的建议时，例如defer缓慢，CGO昂贵，或者始终使用原子操作而不是互斥锁时，请不要猜。

不要因为过时的教条而使您的代码复杂化，并且，如果您认为某些事情很慢，请首先使用基准测试进行证明。Go提供了出色的基准测试和性能分析工具，这些工具均可免费获得。使用它们来找出您程序中的性能瓶颈。

在启动goroutine之前，请知道它何时会停止

在这一点上，我认为我已经从PEP-20中挖掘了有价值的要点，并且可能扩展其重新解释的范围。我认为很好，因为尽管这是一种有用的修辞手法，但最终我们还是在谈论两种不同的语言。

“You type go, a space, and then a function call. Three keystrokes, you can’t make it much shorter than that. Three keystrokes and you’ve just started a sub process.” - Rob Pike, Simplicity is Complicated, dotGo 2015

“您键入go，一个空格和一个函数调用。三次按键，您不能做到比这还短了。三次按键，您就启动了一个子过程。” - 罗伯·派克（Rob Pike），Simplicity is Complicated，dotGo，2015年

接下来的两个建议，我将专注于goroutines。Goroutines是语言的标志性功能，这是我们给出的关于一等公民(first class)并发的答案。它们非常易于使用，只需将单词go放在语句前面，即可异步启动该函数。非常简单，没有线程，没有堆栈大小，没有线程池执行程序(thread pool executor)，没有ID，没有跟踪完成状态。

Goroutines代价很低。由于运行时(runtime)能够将goroutine多路复用到一个小的线程池中（您不必管理），因此可以轻松容纳数十万，数百万个goroutine。这开创了在竞争性并发模型（例如线程或事件回调）下不可行的设计。

但是，即便如goroutine一样便宜，但它们也不是免费的。至少它们的堆栈有几千字节，当您启动10^6个goroutine时，它们的确开始累加。这并不是说就不应该使用数百万个goroutine，如果你的设计需要，可以做。但是当您这样做时，请务必对其进行跟踪，因为10^6数量级的任何东西累计可能消耗的资源都不是少量的。

Goroutines是Go中资源所有权的关键。为了程序有用，goroutine必须做一些事情，这意味着它几乎总是持有对资源的引用或所有权：锁、网络连接、带有数据的缓冲区、channel的发送端。当该goroutine处于活动状态时，将持有锁，保持网络连接打开，保留缓冲区，并且channel的接收器将继续等待更多数据。

释放这些资源的最简单方法是将它们与goroutine的生命周期相关联-当goroutine退出时，资源释放。因此，尽管开始执行goroutine几乎是微不足道的，但在进行三次按键(go+空格)前，请确保您对以下问题有答案：

• goroutine在什么情况下会停止？ Go没有办法告诉goroutine退出。没有停止或终止功能，这是有充分的理由的。如果我们无法命令goroutine停止，则必须礼貌地对其提出要求。这几乎总是归结于channel操作。当channel关闭时，针对一个channel的range loop将退出循环。如果一个channel关闭，它将变为可选(selectable)。从一个goroutine到另一个goroutine的信号最好表示为一个关闭的channel。

• 出现这种情况需要什么？ 如果channel既是在goroutines之间进行通讯的工具，又是它们传达完成信号的机制，那么程序员面临的下一个问题就是，谁将关闭channel，何时会发生？

• 您将使用什么信号知道goroutine已停止？ 当您发出信号告知goroutine要停止时，在将来的某个时间gouroutine停止动作会发生。就人类的感知而言，它可能很快发生，但是计算机每秒执行数十亿条指令，并且从每个goroutine的角度来看，它们的指令执行是不同步的。解决方案通常是使用channel发应答信号或fan-in方法需要的waitgroup。

将并发留给调用者

在您编写的任何严肃的Go程序中，都可能涉及并发。这就提出了一个问题，我们编写的许多库和代码都采用每个连接一个goroutine或采用工作者(worker)模式。您将如何管理这些goroutine的生命周期？

net/http是一个很好的例子。关闭拥有监听套接字的server相对来说是直截了当的，但是从该接受套接字产生的goroutines呢？net/http确实在请求对象中提供了一个上下文(context)对象，该上下文对象可用于向正在监听的代码发出信号，表明应该取消请求(cancel)，从而终止goroutine，但是尚不清楚如何知道何时完成所有这些操作。一种方法是调用context.Cancel，知道取消已经完成是另一回事。²

我想说明的一点net/http是，它是良好实践的反例。由于每个连接都是由net/http.Server类型内部产生的goroutine处理的，因此驻留在程序net/http包外部的程序无法控制接受套接字产生的goroutine。

这是一个仍在不断发展的设计领域，例如go-kit的run.Group和Go团队等努力ErrGroup提供了执行，取消和等待异步运行功能的框架。

这里更大的设计准则是针对库编写者的，或者是任何编写可以异步运行的代码的人，将使用goroutine的责任留给调用者。让调用者选择他们希望如何启动，跟踪和等待函数执行。

编写测试以锁定包API的行为

也许您希望从我这里读到一篇我不咆哮测试的文章。可悲的是，今天不是那天。

测试是关于您的软件做什么和不做什么的契约。程序包级别的单元测试应锁定程序包API的行为。他们用代码描述了程序包承诺要做的事情。如果针对每个输入排列组合都有一个单元测试，那么您已经定义了代码将在代码（而不是文档）中执行的约定 。

通过简单的输入go test，您就可以断言代码是否遵守契约。在任何阶段，您都可以高度自信地知道人们在更改之前所依赖的行为在更改之后将继续有效。

测试会锁定api行为。添加，修改或删除公共api的任何更改都必须包括对其测试的更改。

适度是一种美德

Go是一种简单的语言，只有25个关键字。在某些方面，这使该语言内置的功能脱颖而出。同样，这些是语言销售的功能，轻量级并发，结构化类型。

我想我们所有人都经历过尝试立即使用Go的所有功能所带来的困惑。谁对使用channel如此兴奋以至于他们尽可能多地，尽可能多地使用它们？就我个人而言，我发现结果很难测试，脆弱且最终过于复杂。只有我一个人吗？

我在goroutines上经历了相同的经历，试图将工作分解成很小的单元，我创建了一群难以管理的goroutines，最终观察到我的大多数goroutines总是阻塞等待–代码最终是顺序的，我增加了很多复杂性，几乎没有给现实世界带来任何好处。谁经历过这样的事情？

我在嵌入机制方面(embedding)也有同样的经历。最初，我将其误认为是继承。然后，我通过将已经承担多个职责的复杂类型组合成更复杂的巨大类型重现了创建脆弱的基类问题。

这可能是最不可行的建议，但我认为这一点很重要。建议始终是相同的，所有事情都要适度，Go的特性也不例外。如果可以的话，请不要寻求goroutine或channel，也不要嵌入结构，匿名函数，过渡用package，为每样东西建立接口(interface)，要用简单方法而不是聪明的方法。

可维护性很重要

我想谈谈关于PEP-20的最后一项，

“可读性很重要。” - Python之禅，条款7
“Readability Counts.” - The Zen of Python, Item 7

关于可读性的重要性已经被谈论了很多，不仅在Go语言中，而且在所有编程语言中。像我这样的人，倡导在Go的舞台上使用简单，可读性，清晰度，生产力等词，但最终它们都是一个词的同义词- 可维护性。

真正的目标是编写可维护的代码。原始作者之后的代码可以存活下了。存在的代码不仅可以作为时间点投资，而且可以作为未来价值的基础。不是可读性并不重要，而是可维护性更重要。

Go并不是为聪明人而优化的语言。Go不是一种为了在程序中编写最少行数而进行优化的语言。我们没有针对磁盘上源代码的大小进行优化，也没有针对将程序键入编辑器花费的时间进行优化。而是，我们希望优化我们的代码以使读者清晰(clear)。因为需要维护此代码的人正是读者。

如果您是为自己编写程序，则也许只需要运行一次，或者您是唯一会看到该程序的人，然后程序为您工作。但是，如果这是一个将由多个人贡献的软件，或者将由人们使用足够长的时间以致其需求，功能或运行环境可能发生变化，那么您的目标必须是针对程序的可维护性。如果无法维护软件，则它将被重写；那可能是您的公司最后一次投资Go。

你离开后，您努力实现东西可以维护吗？您今天该如何做才能使某人明天更容易维护您的代码？

---

---

我的网课“Kubernetes实战：高可用集群搭建、配置、运维与应用”在慕课网上线了，感谢小伙伴们学习支持！

我爱发短信：企业级短信平台定制开发专家 https://tonybai.com/
smspush : 可部署在企业内部的定制化短信平台，三网覆盖，不惧大并发接入，可定制扩展； 短信内容你来定，不再受约束, 接口丰富，支持长短信，签名可选。

著名云主机服务厂商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
微信公众号：iamtonybai
博客：tonybai.com
github: https://github.com/bigwhite

微信赞赏：

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

Uber是世界领先的生活出行服务提供商，也是Go语言的早期adopter，根据Uber工程博客的内容，大致可以判断出Go语言在Uber内部扮演了十分重要的角色。Uber内部的Go语言工程实践也是硕果累累，有大量Go实现的内部工具被Uber开源到github上，诸如被Gopher圈熟知的zap、jaeger等。2018年年末Uber将内部的Go风格规范开源到github，经过一年的积累和更新，该规范已经初具规模，并受到广大Gopher的关注。本文是该规范的中文版本，并”夹带“了部分笔者的点评，希望对国内Gopher有所帮助。

注：该版本基于commit 3baa2bd翻译，后续不会持续更新。

一. 介绍

样式(style)是支配我们代码的惯例。术语“样式”有点用词不当，因为这些约定涵盖的范围不限于由gofmt替我们处理的源文件格式。

本指南的目的是通过详细描述在Uber编写Go代码的注意事项来管理这种复杂性。这些规则的存在是为了使代码库易于管理，同时仍然允许工程师更有效地使用Go语言功能。

该指南最初由Prashant Varanasi和Simon Newton编写，目的是使一些同事能快速使用Go。多年来，该指南已根据其他人的反馈进行了修改。

本文档记录了我们在Uber遵循的Go代码中的惯用约定。其中许多是Go的通用准则，而其他扩展准则依赖于下面外部的指南：

• Effective Go
• The Go common mistakes guide

所有代码都应该通过golint和go vet的检查并无错误。我们建议您将编辑器设置为：

• 保存时运行goimports
• 运行golint和go vet检查源码

您可以在以下Go编辑器工具支持页面中找到更为详细的信息：https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins

二. 指导原则

指向interface的指针

您几乎不需要指向接口类型的指针。您应该将接口作为值进行传递，在这样的传递过程中，实质上传递的底层数据仍然可以是指针。

接口实质上在底层用两个字段表示：

• 一个指向某些特定类型信息的指针。您可以将其视为“类型”。
• 数据指针。如果存储的数据是指针，则直接存储。如果存储的数据是一个值，则存储指向该值的指针。

如果要接口方法修改底层数据，则必须用指向目标对象的指针赋值给接口类型变量(译注：感觉原指南中这里表达过于简略，不是很清晰，因此在翻译时增加了自己的一些诠释)。

接收器(receiver)与接口

使用值接收器的方法既可以通过值调用，也可以通过指针调用。

例如:

type S struct {
  data string
}

func (s S) Read() string {
  return s.data
}

func (s *S) Write(str string) {
  s.data = str
}

sVals := map[int]S{1: {"A"}}

// 你只能通过值调用Read
sVals[1].Read()

// 下面无法通过编译：
//  sVals[1].Write("test")

sPtrs := map[int]*S{1: {"A"}}

// 通过指针既可以调用Read，也可以调用Write方法
sPtrs[1].Read()
sPtrs[1].Write("test")

同样，即使该方法具有值接收器，也可以通过指针来满足接口。

type F interface {
  f()
}

type S1 struct{}

func (s S1) f() {}

type S2 struct{}

func (s *S2) f() {}

s1Val := S1{}
s1Ptr := &S1{}
s2Val := S2{}
s2Ptr := &S2{}

var i F
i = s1Val
i = s1Ptr
i = s2Ptr

// 下面代码无法通过编译。因为s2Val是一个值，而S2的f方法中没有使用值接收器
//   i = s2Val

《Effective Go》中有一段关于“pointers vs values”的精彩讲解。

译注：关于Go类型的method集合的问题，在我之前的文章《关于Go，你可能不注意的7件事》中有详尽说明。

零值Mutex是有效的

sync.Mutex和sync.RWMutex是有效的。因此你几乎不需要一个指向mutex的指针。

Bad:

mu := new(sync.Mutex)
mu.Lock()

vs.

Good:

var mu sync.Mutex
mu.Lock()

如果你使用结构体指针，mutex可以非指针形式作为结构体的组成字段，或者更好的方式是直接嵌入到结构体中。

如果是私有结构体类型或是要实现Mutex接口的类型，我们可以使用嵌入mutex的方法：

type smap struct {
  sync.Mutex

  data map[string]string
}

func newSMap() *smap {
  return &smap{
    data: make(map[string]string),
  }
}

func (m *smap) Get(k string) string {
  m.Lock()
  defer m.Unlock()

  return m.data[k]
}

对于导出类型，请使用私有锁：

type SMap struct {
  mu sync.Mutex

  data map[string]string
}

func NewSMap() *SMap {
  return &SMap{
    data: make(map[string]string),
  }
}

func (m *SMap) Get(k string) string {
  m.mu.Lock()
  defer m.mu.Unlock()

  return m.data[k]
}

在边界处拷贝Slices和Maps

slices和maps包含了指向底层数据的指针，因此在需要复制它们时要特别注意。

接收Slices和Maps

请记住，当map或slice作为函数参数传入时，如果您存储了对它们的引用，则用户可以对其进行修改。

Bad

func (d *Driver) SetTrips(trips []Trip) {
  d.trips = trips
}

trips := ...
d1.SetTrips(trips)

// 你是要修改d1.trips吗？
trips[0] = ...

vs.

Good

func (d *Driver) SetTrips(trips []Trip) {
  d.trips = make([]Trip, len(trips))
  copy(d.trips, trips)
}

trips := ...
d1.SetTrips(trips)

// 这里我们修改trips[0]，但不会影响到d1.trips
trips[0] = ...

返回slices或maps

同样，请注意用户对暴露内部状态的map或slice的修改。

Bad

type Stats struct {
  sync.Mutex

  counters map[string]int
}

// Snapshot返回当前状态
func (s *Stats) Snapshot() map[string]int {
  s.Lock()
  defer s.Unlock()

  return s.counters
}

// snapshot不再受到锁的保护
snapshot := stats.Snapshot()

vs.

Good

type Stats struct {
  sync.Mutex

  counters map[string]int
}

func (s *Stats) Snapshot() map[string]int {
  s.Lock()
  defer s.Unlock()

  result := make(map[string]int, len(s.counters))
  for k, v := range s.counters {
    result[k] = v
  }
  return result
}

// snapshot现在是一个拷贝
snapshot := stats.Snapshot()

使用defer做清理

使用defer清理资源，诸如文件和锁。

Bad

p.Lock()
if p.count < 10 {
  p.Unlock()
  return p.count
}

p.count++
newCount := p.count
p.Unlock()

return newCount

// 当有多个return分支时，很容易遗忘unlock

vs.

Good

p.Lock()
defer p.Unlock()

if p.count < 10 {
  return p.count
}

p.count++
return p.count

// 更可读

Defer的开销非常小，只有在您可以证明函数执行时间处于纳秒级的程度时，才应避免这样做。使用defer提升可读性是值得的，因为使用它们的成本微不足道。尤其适用于那些不仅仅是简单内存访问的较大的方法，在这些方法中其他计算的资源消耗远超过defer。

Channel的size要么是1，要么是无缓冲的

channel通常size应为1或是无缓冲的。默认情况下，channel是无缓冲的，其size为零。任何其他尺寸都必须经过严格的审查。考虑如何确定大小，是什么阻止了channel在负载下被填满并阻止写入，以及发生这种情况时发生了什么。

Bad

// 应该足以满足任何人
c := make(chan int, 64)

vs.

Good

// 大小：1
c := make(chan int, 1) // 或
// 无缓冲channel，大小为0
c := make(chan int)

枚举从1开始

在Go中引入枚举的标准方法是声明一个自定义类型和一个使用了iota的const组。由于变量的默认值为0，因此通常应以非零值开头枚举。

Bad

type Operation int

const (
  Add Operation = iota
  Subtract
  Multiply
)

// Add=0, Subtract=1, Multiply=2

vs.

Good

type Operation int

const (
  Add Operation = iota + 1
  Subtract
  Multiply
)

// Add=1, Subtract=2, Multiply=3

在某些情况下，使用零值是有意义的(枚举从零开始)，例如，当零值是理想的默认行为时。

type LogOutput int

const (
  LogToStdout LogOutput = iota
  LogToFile
  LogToRemote
)

// LogToStdout=0, LogToFile=1, LogToRemote=2

错误类型

Go中有多种声明错误（Error)的选项：

• errors.New 对于简单静态字符串的错误
• fmt.Errorf 用于格式化的错误字符串
• 实现Error()方法的自定义类型
• 使用 “pkg/errors”.Wrap的wrapped error

返回错误时，请考虑以下因素以确定最佳选择：

• 这是一个不需要额外信息的简单错误吗？如果是这样，errors.New 就足够了。
• 客户需要检测并处理此错误吗？如果是这样，则应使用自定义类型并实现该Error()方法。
• 您是否正在传播下游函数返回的错误？如果是这样，请查看本文后面有关错误包装(Error Wrap)部分的内容
• 否则，fmt.Errorf就可以。

如果客户端需要检测错误，并且您已使用创建了一个简单的错误errors.New，请使用一个错误变量(sentinel error )。

Bad

// package foo

func Open() error {
  return errors.New("could not open")
}

// package bar

func use() {
  if err := foo.Open(); err != nil {
    if err.Error() == "could not open" {
      // handle
    } else {
      panic("unknown error")
    }
  }
}

vs.

Good

// package foo

var ErrCouldNotOpen = errors.New("could not open")

func Open() error {
  return ErrCouldNotOpen
}

// package bar

if err := foo.Open(); err != nil {
  if err == foo.ErrCouldNotOpen {
    // handle
  } else {
    panic("unknown error")
  }
}

如果您有可能需要客户端检测的错误，并且想向其中添加更多信息（例如，它不是静态字符串），则应使用自定义类型。

Bad

func open(file string) error {
  return fmt.Errorf("file %q not found", file)
}

func use() {
  if err := open(); err != nil {
    if strings.Contains(err.Error(), "not found") {
      // handle
    } else {
      panic("unknown error")
    }
  }
}

vs.

Good

type errNotFound struct {
  file string
}

func (e errNotFound) Error() string {
  return fmt.Sprintf("file %q not found", e.file)
}

func open(file string) error {
  return errNotFound{file: file}
}

func use() {
  if err := open(); err != nil {
    if _, ok := err.(errNotFound); ok {
      // handle
    } else {
      panic("unknown error")
    }
  }
}

直接导出自定义错误类型时要小心，因为它们已成为程序包公共API的一部分。最好公开匹配器功能以检查错误。

// package foo

type errNotFound struct {
  file string
}

func (e errNotFound) Error() string {
  return fmt.Sprintf("file %q not found", e.file)
}

func IsNotFoundError(err error) bool {
  _, ok := err.(errNotFound)
  return ok
}

func Open(file string) error {
  return errNotFound{file: file}
}

// package bar

if err := foo.Open("foo"); err != nil {
  if foo.IsNotFoundError(err) {
    // handle
  } else {
    panic("unknown error")
  }
}

错误包装(Error Wrapping)

一个(函数/方法)调用失败时，有三种主要的错误传播方式：

• 如果没有要添加的其他上下文，并且您想要维护原始错误类型，则返回原始错误。
• 添加上下文，使用”pkg/errors”.Wrap以便错误消息提供更多上下文，”pkg/errors”.Cause可用于提取原始错误。
• 使用fmt.Errorf，如果调用者不需要检测或处理的特定错误情况。

建议在可能的地方添加上下文，以使您获得诸如“调用服务foo：连接被拒绝”之类的更有用的错误，而不是诸如“连接被拒绝”之类的模糊错误。

在将上下文添加到返回的错误时，请避免使用“ failed to”之类的短语来保持上下文简洁，这些短语会陈述明显的内容，并随着错误在堆栈中的渗透而逐渐堆积：

Bad

s, err := store.New()
if err != nil {
    return fmt.Errorf(
        "failed to create new store: %s", err)
}

failed to x: failed to y: failed to create new store: the error

vs.

Good

s, err := store.New()
if err != nil {
    return fmt.Errorf(
        "new store: %s", err)
}

x: y: new store: the error

但是，一旦将错误发送到另一个系统，就应该明确消息是错误消息（例如使用err标记，或在日志中以”Failed”为前缀）。

另请参见Don’t just check errors, handle them gracefully.

处理类型断言失败

类型断言的单个返回值形式针对不正确的类型将产生panic。因此，请始终使用“comma ok”的惯用法。

Bad

t := i.(string)

vs.

Good

t, ok := i.(string)
if !ok {
  // 优雅地处理错误
}

不要panic

在生产环境中运行的代码必须避免出现panic。panic是级联失败的主要根源 。如果发生错误，该函数必须返回错误，并允许调用方决定如何处理它。

Bad

func foo(bar string) {
  if len(bar) == 0 {
    panic("bar must not be empty")
  }
  // ...
}

func main() {
  if len(os.Args) != 2 {
    fmt.Println("USAGE: foo <bar>")
    os.Exit(1)
  }
  foo(os.Args[1])
}

vs.

Good

func foo(bar string) error {
  if len(bar) == 0
    return errors.New("bar must not be empty")
  }
  // ...
  return nil
}

func main() {
  if len(os.Args) != 2 {
    fmt.Println("USAGE: foo <bar>")
    os.Exit(1)
  }
  if err := foo(os.Args[1]); err != nil {
    panic(err)
  }
}

panic/recover不是错误处理策略。仅当发生不可恢复的事情（例如:nil引用）时，程序才必须panic。程序初始化是一个例外：程序启动时应使程序中止的不良情况可能会引起panic。

var _statusTemplate = template.Must(template.New("name").Parse("_statusHTML"))

即便是在test中，也优先使用t.Fatal或t.FailNow来标记test是失败的，而不是panic。

Bad

// func TestFoo(t *testing.T)

f, err := ioutil.TempFile("", "test")
if err != nil {
  panic("failed to set up test")
}

vs.

Good

// func TestFoo(t *testing.T)

f, err := ioutil.TempFile("", "test")
if err != nil {
  t.Fatal("failed to set up test")
}

使用go.uber.org/atomic

使用sync/atomic包的原子操作对原始类型（int32，int64等）进行操作(译注：指atomic包的方法名中均使用原始类型名，如SwapInt32等)，因此很容易忘记使用原子操作来读取或修改变量。

go.uber.org/atomic通过隐藏基础类型为这些操作增加了类型安全性。此外，它包括一个方便的atomic.Bool类型。

Bad

type foo struct {
  running int32  // atomic
}

func (f* foo) start() {
  if atomic.SwapInt32(&f.running, 1) == 1 {
     // already running…
     return
  }
  // start the Foo
}

func (f *foo) isRunning() bool {
  return f.running == 1  // race!
}

vs.

Good

type foo struct {
  running atomic.Bool
}

func (f *foo) start() {
  if f.running.Swap(true) {
     // already running…
     return
  }
  // start the Foo
}

func (f *foo) isRunning() bool {
  return f.running.Load()
}

三. 性能

性能方面的特定准则，适用于热路径。

优先使用strconv而不是fmt

将原语转换为字符串或从字符串转换时，strconv速度比fmt快。

Bad

for i := 0; i < b.N; i++ {
  s := fmt.Sprint(rand.Int())
}

BenchmarkFmtSprint-4    143 ns/op    2 allocs/op

vs.

Good

for i := 0; i < b.N; i++ {
  s := strconv.Itoa(rand.Int())
}

BenchmarkStrconv-4    64.2 ns/op    1 allocs/op

避免字符串到字节的转换

不要反复从固定字符串创建字节slice。相反，请执行一次转换并捕获结果。

Bad

for i := 0; i < b.N; i++ {
  w.Write([]byte("Hello world"))
}

BenchmarkBad-4   50000000   22.2 ns/op

vs.

Good

data := []byte("Hello world")
for i := 0; i < b.N; i++ {
  w.Write(data)
}

BenchmarkGood-4  500000000   3.25 ns/op

四. 样式

相似的声明放在一组

Go语言支持将相似的声明放在一个组内：

Bad

import "a"
import "b"

vs.

Good

import (
  "a"
  "b"
)

这同样适用于常量、变量和类型声明：

Bad

const a = 1
const b = 2

var a = 1
var b = 2

type Area float64
type Volume float64

vs.

Good

const (
  a = 1
  b = 2
)

var (
  a = 1
  b = 2
)

type (
  Area float64
  Volume float64
)

仅将相关的声明放在一组。不要将不相关的声明放在一组。

Bad

type Operation int

const (
  Add Operation = iota + 1
  Subtract
  Multiply
  ENV_VAR = "MY_ENV"
)

vs.

Good

type Operation int

const (
  Add Operation = iota + 1
  Subtract
  Multiply
)

const ENV_VAR = "MY_ENV"

分组使用的位置没有限制，例如：你可以在函数内部使用它们：

Bad

func f() string {
  var red = color.New(0xff0000)
  var green = color.New(0x00ff00)
  var blue = color.New(0x0000ff)

  ...
}

vs.

Good

func f() string {
  var (
    red   = color.New(0xff0000)
    green = color.New(0x00ff00)
    blue  = color.New(0x0000ff)
  )

  ...
}

import组内的包导入顺序

应该有两类导入组：

• 标准库
• 其他一切

默认情况下，这是goimports应用的分组。

Bad

import (
  "fmt"
  "os"
  "go.uber.org/atomic"
  "golang.org/x/sync/errgroup"
)

vs.

Good

import (
  "fmt"
  "os"

  "go.uber.org/atomic"
  "golang.org/x/sync/errgroup"
)

包名

当命名包时，请按下面规则选择一个名称：

• 全部小写。没有大写或下划线。
• 大多数使用命名导入的情况下，不需要重命名。
• 简短而简洁。请记住，在每个使用的地方都完整标识了该名称。
• 不用复数。例如net/url，而不是net/urls。
• 不是“common”，“util”，“shared”或“lib”。这些是不好的，信息量不足的名称。

另请参阅Go包名称和Go包样式指南。

函数名

我们遵循Go社区关于使用MixedCaps作为函数名的约定。有一个例外，为了对相关的测试用例进行分组，函数名可能包含下划线，如: TestMyFunction_WhatIsBeingTested。

包导入别名

如果程序包名称与导入路径的最后一个元素不匹配，则必须使用导入别名。

import (
  "net/http"

  client "example.com/client-go"
  trace "example.com/trace/v2"
)

在所有其他情况下，除非导入之间有直接冲突，否则应避免导入别名。

Bad

import (
  "fmt"
  "os"

  nettrace "golang.net/x/trace"
)

vs.

Good

import (
  "fmt"
  "os"
  "runtime/trace"

  nettrace "golang.net/x/trace"
)

函数分组与顺序

• 函数应按粗略的调用顺序排序。
• 同一文件中的函数应按接收者分组。

因此，导出的函数应先出现在文件中，放在struct、const和var定义的后面。

在定义类型之后，但在接收者的其余方法之前，可能会出现一个newXYZ()/ NewXYZ()。

由于函数是按接收者分组的，因此普通工具函数应在文件末尾出现。

Bad

func (s *something) Cost() {
  return calcCost(s.weights)
}

type something struct{ ... }

func calcCost(n int[]) int {...}

func (s *something) Stop() {...}

func newSomething() *something {
    return &something{}
}

vs.

Good

type something struct{ ... }

func newSomething() *something {
    return &something{}
}

func (s *something) Cost() {
  return calcCost(s.weights)
}

func (s *something) Stop() {...}

func calcCost(n int[]) int {...}

减少嵌套

代码应通过尽可能先处理错误情况/特殊情况并尽早返回或继续循环来减少嵌套。减少嵌套多个级别的代码的代码量。

Bad

for _, v := range data {
  if v.F1 == 1 {
    v = process(v)
    if err := v.Call(); err == nil {
      v.Send()
    } else {
      return err
    }
  } else {
    log.Printf("Invalid v: %v", v)
  }
}

vs.

Good

for _, v := range data {
  if v.F1 != 1 {
    log.Printf("Invalid v: %v", v)
    continue
  }

  v = process(v)
  if err := v.Call(); err != nil {
    return err
  }
  v.Send()
}

不必要的else

如果在if的两个分支中都设置了变量，则可以将其替换为单个if。

Bad

var a int
if b {
  a = 100
} else {
  a = 10
}

vs.

Good

a := 10
if b {
  a = 100
}

顶层变量声明

在顶层，使用标准var关键字。请勿指定类型，除非它与表达式的类型不同。

Bad

var _s string = F()

func F() string { return "A" }

vs.

Good

var _s = F()
// 由于F已经明确了返回一个字符串类型，因此我们没有必要显式指定_s的类型

func F() string { return "A" }

如果表达式的类型与所需的类型不完全匹配，请指定类型。

type myError struct{}

func (myError) Error() string { return "error" }

func F() myError { return myError{} }

var _e error = F()
// F返回一个myError类型的实例，但是我们要error类型

对于未导出的顶层常量和变量，使用_作为前缀

译注：这个是Uber内部的惯用法，目前看并不普适。

在未导出的顶级vars和consts， 前面加上前缀_，以使它们在使用时明确表示它们是全局符号。

例外：未导出的错误值，应以err开头。

基本依据：顶级变量和常量具有包范围作用域。使用通用名称可能很容易在其他文件中意外使用错误的值。

Bad

// foo.go

const (
  defaultPort = 8080
  defaultUser = "user"
)

// bar.go

func Bar() {
  defaultPort := 9090
  ...
  fmt.Println("Default port", defaultPort)

  // We will not see a compile error if the first line of
  // Bar() is deleted.
}

vs.

Good

// foo.go

const (
  _defaultPort = 8080
  _defaultUser = "user"
)

结构体中的嵌入

嵌入式类型（例如mutex）应位于结构体内的字段列表的顶部，并且必须有一个空行将嵌入式字段与常规字段分隔开。

Bad

type Client struct {
  version int
  http.Client
}

vs.

Good

type Client struct {
  http.Client

  version int
}

使用字段名初始化结构体

初始化结构体时，几乎始终应该指定字段名称。现在由go vet强制执行。

Bad

k := User{"John", "Doe", true}

vs.

Good

k := User{
    FirstName: "John",
    LastName: "Doe",
    Admin: true,
}

例外：如果有3个或更少的字段，则可以在测试表中省略字段名称。

tests := []struct{
}{
  op Operation
  want string
}{
  {Add, "add"},
  {Subtract, "subtract"},
}

本地变量声明

如果将变量明确设置为某个值，则应使用短变量声明形式（:=）。

Bad

var s = "foo"

vs.

Good

s := "foo"

但是，在某些情况下，var 使用关键字时默认值会更清晰。例如，声明空切片。

Bad

func f(list []int) {
  filtered := []int{}
  for _, v := range list {
    if v > 10 {
      filtered = append(filtered, v)
    }
  }
}

vs.

Good

func f(list []int) {
  var filtered []int
  for _, v := range list {
    if v > 10 {
      filtered = append(filtered, v)
    }
  }
}

nil是一个有效的slice

nil是一个有效的长度为0的slice，这意味着：

• 您不应明确返回长度为零的切片。返回nil 来代替。

Bad

if x == "" {
  return []int{}
}

vs.

Good

if x == "" {
  return nil
}

• 要检查切片是否为空，请始终使用len(s) == 0。不要检查 nil。

Bad

func isEmpty(s []string) bool {
  return s == nil
}

vs.

Good

func isEmpty(s []string) bool {
  return len(s) == 0
}

• 零值切片可立即使用，无需调用make创建。

Bad

nums := []int{}
// or, nums := make([]int)

if add1 {
  nums = append(nums, 1)
}

if add2 {
  nums = append(nums, 2)
}

vs.

Good

var nums []int

if add1 {
  nums = append(nums, 1)
}

if add2 {
  nums = append(nums, 2)
}

缩小变量作用域

如果有可能，尽量缩小变量作用范围。除非它与减少嵌套的规则冲突。

Bad

err := ioutil.WriteFile(name, data, 0644)
if err != nil {
    return err
}

vs.

Good

if err := ioutil.WriteFile(name, data, 0644); err != nil {
    return err
}

如果需要在if之外使用函数调用的结果，则不应尝试缩小范围。

Bad

if data, err := ioutil.ReadFile(name); err == nil {
  err = cfg.Decode(data)
  if err != nil {
    return err
  }

  fmt.Println(cfg)
  return nil
} else {
  return err
}

vs.

Good

data, err := ioutil.ReadFile(name)
if err != nil {
   return err
}

if err := cfg.Decode(data); err != nil {
  return err
}

fmt.Println(cfg)
return nil

避免裸参数

函数调用中的裸参数可能会损害可读性。当参数名称的含义不明显时，请为参数添加C样式注释（/* … */）。

Bad

// func printInfo(name string, isLocal, done bool)

printInfo("foo", true, true)

vs.

Good

// func printInfo(name string, isLocal, done bool)

printInfo("foo", true /* isLocal */, true /* done */)

更好的作法是，将裸bool类型替换为自定义类型，以获得更易读和类型安全的代码。将来，该参数不仅允许两个状态（true/false）。

type Region int

const (
  UnknownRegion Region = iota
  Local
)

type Status int

const (
  StatusReady = iota + 1
  StatusDone
  // Maybe we will have a StatusInProgress in the future.
)

func printInfo(name string, region Region, status Status)

使用原始字符串字面值，避免转义

Go支持原始字符串字面值，可以跨越多行并包含引号。使用这些字符串可以避免更难阅读的手工转义的字符串。

Bad

wantError := "unknown name:\"test\""

vs.

Good

wantError := `unknown error:"test"`

初始化结构体引用

在初始化结构引用时，请使用&T{}代替new(T)，以使其与结构体初始化一致。

Bad

sval := T{Name: "foo"}

// 不一致
sptr := new(T)
sptr.Name = "bar"

vs.

Good

sval := T{Name: "foo"}

sptr := &T{Name: "bar"}

格式化字符串放在Printf外部

如果你为Printf-style函数声明格式字符串，请将格式化字符串放在外面，并将其设置为const常量。

这有助于go vet对格式字符串执行静态分析。

Bad

msg := "unexpected values %v, %v\n"
fmt.Printf(msg, 1, 2)

vs.

Good

const msg = "unexpected values %v, %v\n"
fmt.Printf(msg, 1, 2)

命名Printf样式的函数

声明Printf-style函数时，请确保go vet可以检测到它并检查格式字符串。

这意味着您应尽可能使用预定义的Printf-style函数名称。go vet将默认检查这些。有关更多信息，请参见Printf系列。

如果不能使用预定义的名称，请以f结束选择的名称：Wrapf，而不是Wrap。go vet可以要求检查特定的Printf样式名称，但名称必须以f结尾。

$ go vet -printfuncs = wrapf,statusf

另请参阅”go vet：Printf家族检查“。

五. 模式

测试表

在核心测试逻辑重复时，将表驱动测试与子测试一起使用，以避免重复代码。

Bad

// func TestSplitHostPort(t *testing.T)

host, port, err := net.SplitHostPort("192.0.2.0:8000")
require.NoError(t, err)
assert.Equal(t, "192.0.2.0", host)
assert.Equal(t, "8000", port)

host, port, err = net.SplitHostPort("192.0.2.0:http")
require.NoError(t, err)
assert.Equal(t, "192.0.2.0", host)
assert.Equal(t, "http", port)

host, port, err = net.SplitHostPort(":8000")
require.NoError(t, err)
assert.Equal(t, "", host)
assert.Equal(t, "8000", port)

host, port, err = net.SplitHostPort("1:8")
require.NoError(t, err)
assert.Equal(t, "1", host)
assert.Equal(t, "8", port)

vs.

Good

// func TestSplitHostPort(t *testing.T)

tests := []struct{
  give     string
  wantHost string
  wantPort string
}{
  {
    give:     "192.0.2.0:8000",
    wantHost: "192.0.2.0",
    wantPort: "8000",
  },
  {
    give:     "192.0.2.0:http",
    wantHost: "192.0.2.0",
    wantPort: "http",
  },
  {
    give:     ":8000",
    wantHost: "",
    wantPort: "8000",
  },
  {
    give:     "1:8",
    wantHost: "1",
    wantPort: "8",
  },
}

for _, tt := range tests {
  t.Run(tt.give, func(t *testing.T) {
    host, port, err := net.SplitHostPort(tt.give)
    require.NoError(t, err)
    assert.Equal(t, tt.wantHost, host)
    assert.Equal(t, tt.wantPort, port)
  })
}

测试表使向错误消息添加上下文，减少重复的逻辑以及添加新的测试用例变得更加容易。

我们遵循这样的约定：将结构体切片称为tests。 每个测试用例称为tt。此外，我们鼓励使用give和want前缀说明每个测试用例的输入和输出值。

tests := []struct{
  give     string
  wantHost string
  wantPort string
}{
  // ...
}

for _, tt := range tests {
  // ...
}

功能选项

功能选项是一种模式，您可以在其中声明一个不透明Option类型，该类型在某些内部结构中记录信息。您接受这些选项的可变编号，并根据内部结构上的选项记录的全部信息采取行动。

将此模式用于您需要扩展的构造函数和其他公共API中的可选参数，尤其是在这些功能上已经具有三个或更多参数的情况下。

Bad

// package db

func Connect(
  addr string,
  timeout time.Duration,
  caching bool,
) (*Connection, error) {
  // ...
}

// Timeout and caching must always be provided,
// even if the user wants to use the default.

db.Connect(addr, db.DefaultTimeout, db.DefaultCaching)
db.Connect(addr, newTimeout, db.DefaultCaching)
db.Connect(addr, db.DefaultTimeout, false /* caching */)
db.Connect(addr, newTimeout, false /* caching */)

vs.

Good

type options struct {
  timeout time.Duration
  caching bool
}

// Option overrides behavior of Connect.
type Option interface {
  apply(*options)
}

type optionFunc func(*options)

func (f optionFunc) apply(o *options) {
  f(o)
}

func WithTimeout(t time.Duration) Option {
  return optionFunc(func(o *options) {
    o.timeout = t
  })
}

func WithCaching(cache bool) Option {
  return optionFunc(func(o *options) {
    o.caching = cache
  })
}

// Connect creates a connection.
func Connect(
  addr string,
  opts ...Option,
) (*Connection, error) {
  options := options{
    timeout: defaultTimeout,
    caching: defaultCaching,
  }

  for _, o := range opts {
    o.apply(&options)
  }

  // ...
}

// Options must be provided only if needed.

db.Connect(addr)
db.Connect(addr, db.WithTimeout(newTimeout))
db.Connect(addr, db.WithCaching(false))
db.Connect(
  addr,
  db.WithCaching(false),
  db.WithTimeout(newTimeout),
)

还可以参考下面资料：

• Self-referential functions and the design of options
• Functional options for friendly APIs

---

我的网课“Kubernetes实战：高可用集群搭建、配置、运维与应用”在慕课网上线了，感谢小伙伴们学习支持！

我爱发短信：企业级短信平台定制开发专家 https://tonybai.com/
smspush : 可部署在企业内部的定制化短信平台，三网覆盖，不惧大并发接入，可定制扩展； 短信内容你来定，不再受约束, 接口丰富，支持长短信，签名可选。

著名云主机服务厂商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
微信公众号：iamtonybai
博客：tonybai.com
github: https://github.com/bigwhite

微信赞赏：

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