100个Go语言典型错误

2019 年，我开始了自己的第二次职业经历，工作中以Go 作为主要开发语言。在这个新的环境中工作时，我注意到了一些关于Go 编码错误的常见模式。我开始思考，写了一些关于这些常见错误的文章，这些文章或许可以帮助一些开发人员。

后来，我写了一篇博客文章，名为“我在Go 项目中看到的十个最常见的错误”。这篇文章非常受欢迎：它有超过10 万次的阅读量，并被Golang Weekly 选为2019 年最佳文章之一。

除此之外，我很高兴收到了Go 社区的积极反馈。

从那时起，我意识到讨论常见错误是一个强大的工具。如果还能提供具体的例子，那么它可以有效地帮助人们学习新技能，并有助于记住错误的出现场景以及如何避免类似错误。

我花了大约一年的时间从各种来源收集错误，包括其他专业项目、开源仓库、图书、博客、技术研究及与Go 社区的讨论。坦率地说，我自己的工作也是错误的不错来源之一。

到2020 年年底，我收集了100 个Go 语言的典型错误，这对我来说似乎是合适的时机，可以向出版公司提出我的想法了。我只联系了一家出版公司：Manning。我认为Manning 是一家知名的高质量图书出版公司，对我来说，它是完美的合作伙伴。我花了近两年的时间和无数次的迭代，梳理每一个错误，并提供了有意义的例子和多个解决方案，其中错误的出现场景至关重要。

我希望这本书能帮助大家避免这些常见错误，并帮助大家提高使用Go 语言的熟练程度。

Go语言"入门易，精通难”。想要用Go语言写出优质的软件，不仅要了解Go语言的语法，还需要对Go语言的特性、软件的通用编写方法、软件项目的组织方法、并发程序设计、软件测试、软件性能优化等方面都有一定的了解。

本书既聚焦于Go语言，又不限于Go语言，介绍了开发者在使用Go语言时经常犯的100个经典错误，内容侧重于语言核心和标准库。对大多数错误的讨论都提供了具体的示例，以说明在什么时候容易犯这样的错误。这不是一本教条主义的图书，每个解决方案都详细传达了它应该适用的上下文。

Teiva Harsanyi 是Docker 公司的资深软件工程师，常年研究Go语言及如何设计和实现可靠的应用程序，具有非常丰富的实战经验。
Go语言翻译小组成员（按姓名首字母排序）：晁岳攀、高行、李殿斌、李子昂、马学翔、饶全成、万俊峰、王莹、徐新华、叶王、曾浩浩，译者均为资深软件工程师，对Go语言编写及软件项目实现有丰富的实战经验。

1 Go：入门易，精通难 
1.1 Go 语言概述 
1.2 简单不意味着容易 
1.3 100 个Go 语言错误 
1.3.1 bug 
1.3.2 不必要的复杂性 
1.3.3 可读性差 
1.3.4 非最佳组织形式 
1.3.5 API 对用户不友好 
1.3.6 代码有待优化 
1.3.7 效率低 
总结 
2 代码和项目组织 
2.1 #1：意想不到的变量隐藏 
2.2 #2：不必要的嵌套代码 
2.3 #3：滥用init 函数 
2.3.1 概念 
2.3.2 何时使用init 函数 
2.4 #4：过度使用getter 和setter 
2.5 #5：避免接口污染 
2.5.1 概念 
2.5.2 何时使用接口 
2.5.3 接口污染 
2.6 #6：在生产者端的接口 
2.7 #7：返回接口 
2.8 #8：any 意味着nothing 
2.9 #9：不知道什么时候使用泛型 
2.9.1 概念 
2.9.2 常见的使用方法和误用 
2.10 #10：没有意识到类型嵌入可能存在的问题 
2.11 #11：不使用函数式选项模式 
2.11.1 配置结构体 
2.11.2 生成器模式 
2.11.3 函数式选项模式 
2.12 #12：项目组织混乱 
2.12.1 项目结构 
2.12.2 包组织 
2.13 #13：创建实用程序包 
2.14 #14：忽略包名称冲突 
2.15 #15：缺少代码文档 
2.16 #16：不使用代码检查工具 
总结 
3 数据类型 
3.1 #17：使用八进制字面量会带来混淆 
3.2 #18：容易忽视的整数溢出 
3.2.1 概念 
3.2.2 在递增操作时检测整数溢出 
3.2.3 在加法操作中检测整数溢出 
3.2.4 在乘法操作中检测整数溢出 
3.3 #19：不了解浮点数 
3.4 #20：不了解切片的长度和容量 
3.5 #21：低效的切片初始化 
3.6 #22：对 nil 和空切片的困惑 . 
3.7 #23：未正确检查切片是否为空 
3.8 #24：无法正确复制切片 
3.9 #25：使用append 的副作用 
3.10 #26：切片和内存泄漏 
3.10.1 容量泄漏 
3.10.2 切片和指针 
3.11 #27：低效的 map 初始化 
3.11.1 概念 
3.11.2 初始化 
3.12 #28：map 和内存泄漏 
3.13 #29：比较值时发生的错误 
总结 
4 控制结构 
4.1 #30：忽视在 range 循环中元素被复制的事实 
4.1.1 概念 
4.1.2 值复制 
4.2 #31：忽视 range 循环中参数是如何求值的 
4.2.1 channel 
4.2.2 数组 
4.3 #32：忽视在 range 循环中使用指针元素的影响 
4.4 #33：在 map 迭代过程中做出错误假设 
4.4.1 排序 
4.4.2 在迭代时往 map 中添加数据 
4.5 #34：忽视break 语句是如何工作的 
4.6 #35：在循环中使用defer 
总结 
5 字符串 
5.1 #36：不理解 rune 的概念 
5.2 #37：字符串迭代不准确 
5.3 #38：乱用 trim 函数 
5.4 #39：缺乏优化的字符串连接 
5.5 #40：无用的字符串转换 
5.6 #41：子字符串和内存泄漏 
总结 
6 函数与方法 
6.1 #42：不知道使用什么类型的接收器 
6.2 #43：不要使用命名的结果参数 
6.3 #44：使用命名的结果参数的意外副作用 
6.4 #45：返回一个 nil 接收器 
6.5 #46：使用文件名作为函数输入 
6.6 #47：忽略defer 语句参数和接收器的计算 
6.6.1 参数计算 
6.6.2 指针和值接收器 
总结 
7 错误管理 
7.1 #48：panic 
7.2 #49：搞不清何时需要包装错误 
7.3 #50：不准确的错误类型检查 
7.4 #51：错误地检查错误值 
7.5 #52：处理同一个错误两次 
7.6 #53：忽略错误 
7.7 #54：忽略 defer 语句返回的错误 
总结 
8 并发：基础 
8.1 #55：混淆并发和并行 
8.2 #56：认为并发总是更快 
8.2.1 Go 调度 
8.2.2 并行归并排序 
8.3 #57：对何时使用channel 或互斥锁感到困惑 
8.4 #58：不理解竞争问题 
8.4.1 数据竞争与竞争条件 
8.4.2 Go 内存模型 
8.5 #59：不了解工作负载类型对并发的影响 
8.6 #60：误解 Go 上下文 
8.6.1 最后期限 
8.6.2 取消信号 
8.6.3 上下文值 
8.6.4 感知上下文的取消信号 
总结 
9 并发：实践 
9.1 #61：传播不恰当的上下文 
9.2 #62：在不知道何时停止的情况下启动 goroutine 
9.3 #63：没有小心处理 goroutine 和循环变量 
9.4 #64：使用 select 和channel 来期待确定性行为 
9.5 #65：没有使用通知channel 
9.6 #66：没有使用 nil channel 
9.7 #67：对channel 缓冲区大小感到困惑 
9.8 #68：忘记字符串格式化可能产生的副作用 
9.8.1 etcd 数据竞争 
9.8.2 死锁 
9.9 #69：使用 append 函数创造了数据竞争 
9.10 #70：对切片和 map 不准确地使用互斥锁 
9.11 #71：错误使用 sync.WaitGroup 
9.12 #72：忘记了 sync.Cond 
9.13 #73：没有使用 errgroup 
9.14 #74：复制sync 类型 
总结 
10 标准库 
10.1 #75：提供错误的持续时间 
10.2 #76：time.After 和内存泄漏 
10.3 #77：常见的JSON 处理错误 
10.3.1 由嵌入式字段导致的非预期行为 
10.3.2 JSON 和单调时钟 
10.3.3 map 中的any 类型 
10.4 #78：常见的 SQL 错误 
10.4.1 忘记sql.Open 不一定与数据库建立连接 
10.4.2 忘记连接池导致的问题 
10.4.3 未使用预准备的语句 
10.4.4 对空值处理不当 
10.4.5 没有处理行迭代错误 
10.5 #79：没有关闭瞬时资源 
10.5.1 HTTP Body 
10.5.2 sql.Rows 
10.5.3 os.File 
10.6 #80：在响应HTTP 请求后忘记加return 语句 
10.7 #81：使用默认的HTTP 客户端和服务端 
10.7.1 HTTP 客户端 
10.7.2 HTTP 服务端 
总结 
11 测试 
11.1 #82：未区分测试种类 
11.1.1 build 标识 
11.1.2 环境变量 
11.1.3 短模式 
11.2 #83：未打开-race 开关 
11.3 #84：未使用测试执行模式 
11.3.1 parallel 标识 
11.3.2 shuffle 标识 
11.4 #85：未使用表格驱动型测试 
11.5 #86：在单元测试中休眠 
11.6 #87：没有有效处理 time API 
11.7 #88：未使用测试工具包 
11.7.1 httptest 包 
11.7.2 iotest 包 
11.8 #89：写出不准确的基准测试 
11.8.1 未重置或暂停计时器 
11.8.2 对微基准测试做出错误假设 
11.8.3 未注意编译器优化 
11.8.4 被观察者效应愚弄 
11.9 #90：未探索所有的 Go 测试特性 
11.9.1 代码覆盖率 
11.9.2 从一个不同的包进行测试 
11.9.3 工具函数 
11.9.4 设置和拆卸 
总结 
12 优化 
12.1 #91：不了解 CPU 缓存 
12.1.1 CPU 架构 
12.1.2 缓存行 
12.1.3 包含结构体的切片 vs 包含切片的结构体 
12.1.4 可预测性 
12.1.5 缓存放置策略 
12.2 #92：编写导致伪共享的并发代码 
12.3 #93：不考虑指令级并行性 
12.4 #94：不了解数据对齐 
12.5 #95：不了解栈与堆 
12.5.1 栈 vs 堆 
12.5.2 逃逸分析 
12.6 #96：不了解如何减少分配 
12.6.1 修改 API 
12.6.2 编译器优化 
12.6.3 sync.Pool 
12.7 #97：没有依赖内联 
12.8 #98：没有使用Go 诊断工具 
12.8.1 分析工具 
12.8.2 跟踪工具 
12.9 #99：不了解 GC 的工作原理 
12.9.1 概念 
12.9.2 示例 
12.10 #100：不了解在 Docker 和 Kubernetes 中运行Go 程序的影响 
总结 
结语

Go语言"入门易，精通难”。想要用Go语言写出优质的软件，不仅要了解Go语言的语法，还需要对Go语言的特性、软件的通用编写方法、软件项目的组织方法、并发程序设计、软件测试、软件性能优化等方面都有一定的了解。

本书既聚焦于Go语言，又不限于Go语言，介绍了开发者在使用Go语言时经常犯的100个经典错误，内容侧重于语言核心和标准库。对大多数错误的讨论都提供了具体的示例，以说明在什么时候容易犯这样的错误。这不是一本教条主义的图书，每个解决方案都详细传达了它应该适用的上下文。

Teiva Harsanyi 是Docker 公司的资深软件工程师，常年研究Go语言及如何设计和实现可靠的应用程序，具有非常丰富的实战经验。
Go语言翻译小组成员（按姓名首字母排序）：晁岳攀、高行、李殿斌、李子昂、马学翔、饶全成、万俊峰、王莹、徐新华、叶王、曾浩浩，译者均为资深软件工程师，对Go语言编写及软件项目实现有丰富的实战经验。

看到《100 个Go 语言典型错误》中译本即将出版，我特别高兴。距离2021 年12 月底我把本书的英文版推荐给电子工业出版社的滕老师，已经过去了近两年的时间。由于各种原因，我没有参与本书的翻译工作，但是我深知一本书的诞生何其不易。要感谢本书的翻译团队和出版社各位老师的努力，把这么好的一本书带给读者！

我是2013 年年底接触到Go 语言的，很快就被它的各种优势所吸引。2014 年，我们基于Go 语言完成了百度统一前端（BFE）接入平台核心转发引擎的重构，并在2020 年年底实现了每日超过万亿级的请求转发。在中国，BFE 是较早将Go 语言用于负载均衡场景及大规模使用的项目。出于对Go 语言的喜爱，我一直在努力推动Go 语言的推广，这也是我将本书推荐给滕老师的重要原因。

众所周知，Go 语言是一门相对较新的编程语言，于2009 年才正式推出。十多年来，Go语言得到了非常广泛的使用，尤其是在云原生领域，云原生计算基金会的绝大多数官方开源项目都是基于Go 语言编写的。即便如此，很多人对于Go 语言的特点和使用方法并没有深入的研究。正如本书开头所说，Go 语言“入门易，精通难”。要想用Go 语言写出优质的代码，不仅要了解Go 语言的语法，还需要对Go 语言的特性、代码的通用编写方法、软件项目的组织方法、并发程序设计、软件测试、软件性能优化等方面都有一定的了解。

本书的优点在于它既聚焦于Go 语言，又不限于Go 语言。在我看来，学习一门编程语言是相对容易的事情，真正需要长期用心学习的是软件研发的基本理念和原则。本书在讲述Go 语言的同时，还在不断为读者灌输软件研发的各种基本理念。我相信这种“案例学习”的方法对于读者来说是一种较好的方式，也希望读者在阅读时能够体会到作者的这番苦心，能够超越Go 语言来体会本书中的一些观点。

祝各位读者用好Go 语言，祝Go 语言的社区进一步壮大！

章淼博士

BFE 开源项目发起人

《代码的艺术》作者

瑛菲网络创始人&CEO

百度代码规范委员会荣誉主席

本书是一本非常实用的技术指南，为Go 语言开发者提供了解决常见问题的宝贵经验。

无论你是初学者还是有经验的开发者，这本书都能帮助你避免常见的陷阱和错误。通过清晰的解释和实用的示例，它能够帮助你更好地理解Go 语言的工作原理，并提供了一些最佳实践和技巧。如果你想高效且准确地使用Go 语言进行开发，这本书绝对是你的必bei指南！

谢孟军

GoCN 社区发起人、积梦智能CEO

前几年我就关注到了这本书，作者写得非常好，对于开发者而言有较大的参考和学习意义。Go 已经诞生十多年了，语言的生态已经愈发丰富，其特殊性时常会让开发者感到难以理解并随时会“踩坑”。

本书归类、讲解、总结了7 大类常见的错误，共100 个具体的错误例子。在每个例子中，结合不同的场景进行了有针对性的说明，于学习之余也可以扩展你的技术视野。推荐大家多阅读几遍！

陈剑煜

《Go 语言编程之旅》作者

本书是一本实用且全面的Go 语言指南！本书提供了Go 语言开发中常见问题的深入解析和解决方案。这本书不仅适合初学者，也适用于有经验的开发者。无论你是学习、开发还是优化代码，这本书都会成为你的良师益友。

王中阳

北京字节神话CTO

Go 语言是一门简单的编程语言，有一定编程基础的开发者用一个周末的时间即可迅速

掌握Go 语言的基础知识。但是，简单并不代表容易，即便是已经有一些Go 语言使用经验的

开发者，也无法避免使用时出现错误。我们应该认真对待使用Go 语言时常犯的一些错误，

比如认真分析错误出现的原因和如何避免，就像在学生时代，我们整理错题本一样。本书作

者通过整理100 个错误的“Go 语言错题本”，告诉我们使用Go 语言时需要注意的一些陷阱。

本书适合所有使用Go 语言的开发者阅读，我相信本书不仅可以帮助大家降低使用Go 语言开

发项目时出现错误的概率，还可以提升大家使用Go 语言的能力。

魏如博（frank）

公众号“Golang 语言开发栈”主理人

本书作者结合自己多年的Go 开发经验，深入分析了Go 语言的常见错误，并为其进行了

归类。无论你是刚入门还是拥有丰富的Go 开发经验，都应该考虑深入探索这本书。因为你

不仅会了解到错误本身，还能掌握错误背后的上下文，这能让我们从错误中高效地进行学习。

杨文

Go 夜读创始人

正如作者所言，Go 语言简单易学但难以掌握。本书以100 个典型且全面的例子涵盖了

Go 语言开发中的常见错误，并深入探讨了错误发生背后的原因及其对应的解决策略。其中

许多例子都非常经典，是实战中的真实反映。通过这种富有吸引力的方式，读者不仅能够洞

悉实战中的经典错误，还可以学习如何巧妙地规避它们，并在这一过程中更深入地理解Go

语言的特性和最佳实践。

郑建勋

《Go 语言底层原理剖析》及《聚沙成塔：Go 语言构建高性能、分布式爬虫项目》作者