Repository: xxjwxc/uber_go_guide_cn
Branch: master
Commit: 0b729562805e
Files: 67
Total size: 158.7 KB
Directory structure:
gitextract_96pgpcf4/
├── .gitignore
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── LICENSE
├── README.md
└── src/
├── README.md
├── SUMMARY.md
├── atomic.md
├── builtin-name.md
├── channel-size.md
├── consistency.md
├── container-capacity.md
├── container-copy.md
├── decl-group.md
├── defer-clean.md
├── else-unnecessary.md
├── embed-public.md
├── enum-start.md
├── error-name.md
├── error-once.md
├── error-type.md
├── error-wrap.md
├── exit-main.md
├── exit-once.md
├── function-name.md
├── function-order.md
├── functional-option.md
├── global-decl.md
├── global-mut.md
├── global-name.md
├── goroutine-exit.md
├── goroutine-forget.md
├── goroutine-init.md
├── import-alias.md
├── import-group.md
├── init.md
├── interface-compliance.md
├── interface-pointer.md
├── interface-receiver.md
├── intro.md
├── line-length.md
├── lint.md
├── map-init.md
├── mutex-zero-value.md
├── nest-less.md
├── package-name.md
├── panic.md
├── param-naked.md
├── performance.md
├── preface.txt
├── printf-const.md
├── printf-name.md
├── slice-nil.md
├── strconv.md
├── string-byte-slice.md
├── string-escape.md
├── struct-embed.md
├── struct-field-key.md
├── struct-field-zero.md
├── struct-pointer.md
├── struct-tag.md
├── struct-zero.md
├── test-table.md
├── time.md
├── type-assert.md
├── var-decl.md
└── var-scope.md
================================================
FILE CONTENTS
================================================
================================================
FILE: .gitignore
================================================
.idea
================================================
FILE: CHANGELOG.md
================================================
# 2020 年 1 月 30 日
- 建议在处理时间时使用 “time” 包。
# 2020 年 1 月 25 日
- 添加有关在公共结构中嵌入类型的指导。
# 2019 年 12 月 17 日
- 函数选项：推荐 “Option” 接口的结构实现，而不是用闭包捕获值。
# 2019 年 11 月 26 日
- 添加针对全局变量变异的指导。
# 2019 年 10 月 21 日
- 添加与现有实践保持一致的章节。
- 添加有关地图初始化和大小提示的指导。
# 2019 年 10 月 11 日
- 为错误消息建议简洁的上下文。
# 2019 年 10 月 10 日
- 初次发布。
================================================
FILE: CODE_OF_CONDUCT.md
================================================
# Contributor Covenant Code of Conduct
## Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, sex characteristics, gender identity and expression,
level of experience, education, socio-economic status, nationality, personal
appearance, race, religion, or sexual identity and orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at oss-conduct@uber.com. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see
https://www.contributor-covenant.org/faq
================================================
FILE: LICENSE
================================================
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
================================================
FILE: README.md
================================================
<!--
Editing this document:
- Discuss all changes in GitHub issues first.
- Update the table of contents as new sections are added or removed.
- Use tables for side-by-side code samples. See below.
Code Samples:
Use 2 spaces to indent. Horizontal real estate is important in side-by-side
samples.
For side-by-side code samples, use the following snippet.
~~~
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
BAD CODE GOES HERE
```
</td><td>
```go
GOOD CODE GOES HERE
```
</td></tr>
</tbody></table>
~~~
(You need the empty lines between the <td> and code samples for it to be
treated as Markdown.)
If you need to add labels or descriptions below the code samples, add another
row before the </tbody></table> line.
~~~
<tr>
<td>DESCRIBE BAD CODE</td>
<td>DESCRIBE GOOD CODE</td>
</tr>
~~~
-->
<!--
change.md
# 2019-12-17
- 函数选项：推荐“Option”接口的结构实现
- 而不是用闭包捕获值。
# 2019-11-26
- 添加针对全局变量变异的指导。
# 2020-01-11
- 为`open（..）`调用添加缺少的参数。
# 2020-02-03
- 使用 `"time"` 处理时间的建议
- 添加有关在公共结构中嵌入类型的指导。
# 2020-02-25
- 添加有关接口验证是否符合编译时检查的指导。
# 2020-06-05
- 添加避免使用内置名称的指导意见
# 2020-06-10
- 添加 init() 指导意见
# 2020-06-16
- 追加时优先指定切片容量
- 添加有关指针接收器可调用性的说明
# 2020-06-17
- map 和切片的联合指导
# 2020-09-15
- Remove main panic
# 2021-03-17
- 结构体初始化
# 2021-04-19
- 程序只能在`main()`中退出，最好最多退出一次
# 2021-11-16
- 添加有关将 `%w` 与 `%v` 与 `fmt.Errorf` 结合使用的指南，以及在何处使用 `errors.New` 或自定义错误类型。
# 2022-01-05
- 修复翻译错误
- 修复部分失效的链接
# 2022-03-30
- 添加有关在封送结构中使用字段标记的指导。
-
# 2022-10-18
- 管理 goroutine 生命周期的指导。
# 2023-04-13
- Errors: 只添加一次错误处理指南
-->
## [uber-go/guide](https://github.com/uber-go/guide) 的中文翻译
## [English](https://github.com/uber-go/guide/blob/master/style.md)
## Uber Go 语言编码规范
[Uber](https://www.uber.com/) 是一家美国硅谷的科技公司，也是 Go 语言的早期 adopter。其开源了很多 golang 项目，诸如被 Gopher 圈熟知的 [zap](https://github.com/uber-go/zap)、[jaeger](https://github.com/jaegertracing/jaeger) 等。2018 年年末 Uber 将内部的 [Go 风格规范](https://github.com/uber-go/guide) 开源到 GitHub，经过一年的积累和更新，该规范已经初具规模，并受到广大 Gopher 的关注。本文是该规范的中文版本。本版本会根据原版实时更新。
## 版本
- 当前更新版本：2024-08-10 版本地址：[commit:#227](https://github.com/uber-go/guide/commit/97314412dfcb60c3f4f0372bc311f9ddcdac54a9)
- 如果您发现任何更新、问题或改进，请随时 fork 和 PR
- Please feel free to fork and PR if you find any updates, issues or improvement.
## 目录
- [uber-go/guide 的中文翻译](#uber-goguide-的中文翻译)
- [English](#english)
- [Uber Go 语言编码规范](#uber-go-语言编码规范)
- [版本](#版本)
- [目录](#目录)
- [介绍](#介绍)
- [指导原则](#指导原则)
- [指向 interface 的指针](#指向-interface-的指针)
- [Interface 合理性验证](#interface-合理性验证)
- [接收器 (receiver) 与接口](#接收器-receiver-与接口)
- [零值 Mutex 是有效的](#零值-mutex-是有效的)
- [在边界处拷贝 Slices 和 Maps](#在边界处拷贝-slices-和-maps)
- [接收 Slices 和 Maps](#接收-slices-和-maps)
- [返回 slices 或 maps](#返回-slices-或-maps)
- [使用 defer 释放资源](#使用-defer-释放资源)
- [Channel 的 size 要么是 1，要么是无缓冲的](#channel-的-size-要么是-1要么是无缓冲的)
- [枚举从 1 开始](#枚举从-1-开始)
- [使用 time 处理时间](#使用-time-处理时间)
- [使用 `time.Time` 表达瞬时时间](#使用-timetime-表达瞬时时间)
- [使用 `time.Duration` 表达时间段](#使用-timeduration-表达时间段)
- [对外部系统使用 `time.Time` 和 `time.Duration`](#对外部系统使用-timetime-和-timeduration)
- [Errors](#errors)
- [错误类型](#错误类型)
- [错误包装](#错误包装)
- [错误命名](#错误命名)
- [一次处理错误](#一次处理错误)
- [处理断言失败](#处理断言失败)
- [不要使用 panic](#不要使用-panic)
- [使用 go.uber.org/atomic](#使用-gouberorgatomic)
- [避免可变全局变量](#避免可变全局变量)
- [避免在公共结构中嵌入类型](#避免在公共结构中嵌入类型)
- [避免使用内置名称](#避免使用内置名称)
- [避免使用 `init()`](#避免使用-init)
- [追加时优先指定切片容量](#追加时优先指定切片容量)
- [主函数退出方式 (Exit)](#主函数退出方式-exit)
- [一次性退出](#一次性退出)
- [在序列化结构中使用字段标记](#在序列化结构中使用字段标记)
- [不要一劳永逸地使用 goroutine](#不要一劳永逸地使用-goroutine)
- [等待 goroutines 退出](#等待-goroutines-退出)
- [不要在 `init()` 使用 goroutines](#不要在-init-使用-goroutines)
- [性能](#性能)
- [优先使用 strconv 而不是 fmt](#优先使用-strconv-而不是-fmt)
- [避免字符串到字节的转换](#避免字符串到字节的转换)
- [指定容器容量](#指定容器容量)
- [指定 Map 容量提示](#指定-map-容量提示)
- [指定切片容量](#指定切片容量)
- [规范](#规范)
- [避免过长的行](#避免过长的行)
- [一致性](#一致性)
- [相似的声明放在一组](#相似的声明放在一组)
- [import 分组](#import-分组)
- [包名](#包名)
- [函数名](#函数名)
- [导入别名](#导入别名)
- [函数分组与顺序](#函数分组与顺序)
- [减少嵌套](#减少嵌套)
- [不必要的 else](#不必要的-else)
- [顶层变量声明](#顶层变量声明)
- [对于未导出的顶层常量和变量，使用\_作为前缀](#对于未导出的顶层常量和变量使用_作为前缀)
- [结构体中的嵌入](#结构体中的嵌入)
- [本地变量声明](#本地变量声明)
- [nil 是一个有效的 slice](#nil-是一个有效的-slice)
- [缩小变量作用域](#缩小变量作用域)
- [避免参数语义不明确 (Avoid Naked Parameters)](#避免参数语义不明确-avoid-naked-parameters)
- [使用原始字符串字面值，避免转义](#使用原始字符串字面值避免转义)
- [初始化结构体](#初始化结构体)
- [使用字段名初始化结构](#使用字段名初始化结构)
- [省略结构中的零值字段](#省略结构中的零值字段)
- [对零值结构使用 `var`](#对零值结构使用-var)
- [初始化 Struct 引用](#初始化-struct-引用)
- [初始化 Maps](#初始化-maps)
- [字符串 string format](#字符串-string-format)
- [命名 Printf 样式的函数](#命名-printf-样式的函数)
- [编程模式](#编程模式)
- [表驱动测试](#表驱动测试)
- [功能选项](#功能选项)
- [Linting](#linting)
- [Lint Runners](#lint-runners)
- [Stargazers over time](#stargazers-over-time)
## 介绍
样式 (style) 是支配我们代码的惯例。术语`样式`有点用词不当，因为这些约定涵盖的范围不限于由 gofmt 替我们处理的源文件格式。
本指南的目的是通过详细描述在 Uber 编写 Go 代码的注意事项来管理这种复杂性。这些规则的存在是为了使代码库易于管理，同时仍然允许工程师更有效地使用 Go 语言功能。
该指南最初由 [Prashant Varanasi] 和 [Simon Newton] 编写，目的是使一些同事能快速使用 Go。多年来，该指南已根据其他人的反馈进行了修改。
[Prashant Varanasi]: https://github.com/prashantv
[Simon Newton]: https://github.com/nomis52
本文档记录了我们在 Uber 遵循的 Go 代码中的惯用约定。其中许多是 Go 的通用准则，而其他扩展准则依赖于下面外部的指南：
1. [Effective Go](https://golang.org/doc/effective_go.html)
2. [Go Common Mistakes](https://go.dev/wiki/CommonMistakes)
3. [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments)
我们的目标是使代码示例能够准确地用于 Go 的两个发布版本 [releases](https://go.dev/doc/devel/release).
所有代码都应该通过`golint`和`go vet`的检查并无错误。我们建议您将编辑器设置为：
- 保存时运行 `goimports`
- 运行 `golint` 和 `go vet` 检查错误
您可以在以下 Go 编辑器工具支持页面中找到更为详细的信息：
<https://go.dev/wiki/IDEsAndTextEditorPlugins>
## 指导原则
### 指向 interface 的指针
您几乎不需要指向接口类型的指针。您应该将接口作为值进行传递，在这样的传递过程中，实质上传递的底层数据仍然可以是指针。
接口实质上在底层用两个字段表示：
1. 一个指向某些特定类型信息的指针。您可以将其视为"type"。
2. 数据指针。如果存储的数据是指针，则直接存储。如果存储的数据是一个值，则存储指向该值的指针。
如果希望接口方法修改基础数据，则必须使用指针传递 (将对象指针赋值给接口变量)。
```go
type F interface {
f()
}
type S1 struct{}
func (s S1) f() {}
type S2 struct{}
func (s *S2) f() {}
// f1.f() 无法修改底层数据
// f2.f() 可以修改底层数据，给接口变量 f2 赋值时使用的是对象指针
var f1 F = S1{}
var f2 F = &S2{}
```
永远不要使用指向 interface 的指针，这个是没有意义的。在 go 语言中，接口本身就是引用类型，换句话说，接口类型本身就是一个指针。对于我的需求，其实 test 的参数只要是 myinterface 就可以了，只需要在传值的时候，传*mystruct 类型（也只能传*mystruct 类型）
```go
type myinterface interface{
print()
}
func test(value *myinterface){
//someting to do ...
}
type mystruct struct {
i int
}
//实现接口
func (this *mystruct) print(){
fmt.Println(this.i)
this.i=1
}
func main(){
m := &mystruct{0}
test(m) // 错误
test(*m) // 错误
}
```
### Interface 合理性验证
在编译时验证接口的符合性。这包括：
- 将实现特定接口的导出类型作为接口 API 的一部分进行检查
- 实现同一接口的 (导出和非导出) 类型属于实现类型的集合
- 任何违反接口合理性检查的场景，都会终止编译，并通知给用户
补充：上面 3 条是编译器对接口的检查机制，
大体意思是错误使用接口会在编译期报错。
所以可以利用这个机制让部分问题在编译期暴露。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// 如果 Handler 没有实现 http.Handler，会在运行时报错
type Handler struct {
// ...
}
func (h *Handler) ServeHTTP(
w http.ResponseWriter,
r *http.Request,
) {
...
}
```
</td><td>
```go
type Handler struct {
// ...
}
// 用于触发编译期的接口的合理性检查机制
// 如果 Handler 没有实现 http.Handler，会在编译期报错
var _ http.Handler = (*Handler)(nil)
func (h *Handler) ServeHTTP(
w http.ResponseWriter,
r *http.Request,
) {
// ...
}
```
</td></tr>
</tbody></table>
如果 `*Handler` 与 `http.Handler` 的接口不匹配，
那么语句 `var _ http.Handler = (*Handler)(nil)` 将无法编译通过。
赋值的右边应该是断言类型的零值。
对于指针类型（如 `*Handler`）、切片和映射，这是 `nil`；
对于结构类型，这是空结构。
```go
type LogHandler struct {
h http.Handler
log *zap.Logger
}
var _ http.Handler = LogHandler{}
func (h LogHandler) ServeHTTP(
w http.ResponseWriter,
r *http.Request,
) {
// ...
}
```
### 接收器 (receiver) 与接口
使用值接收器的方法既可以通过值调用，也可以通过指针调用。
带指针接收器的方法只能通过指针或 [addressable values] 调用。
[addressable values]: https://golang.org/ref/spec#Method_values
例如，
```go
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")
```
类似的，即使方法有了值接收器，也同样可以用指针接收器来满足接口。
```go
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](https://golang.org/doc/effective_go.html) 中有一段关于 [pointers vs. values](https://golang.org/doc/effective_go.html#pointers_vs_values) 的精彩讲解。
补充：
- 一个类型可以有值接收器方法集和指针接收器方法集
- 值接收器方法集是指针接收器方法集的子集，反之不是
- 规则
- 值对象只可以使用值接收器方法集
- 指针对象可以使用 值接收器方法集 + 指针接收器方法集
- 接口的匹配 (或者叫实现)
- 类型实现了接口的所有方法，叫匹配
- 具体的讲，要么是类型的值方法集匹配接口，要么是指针方法集匹配接口
具体的匹配分两种：
- 值方法集和接口匹配
- 给接口变量赋值的不管是值还是指针对象，都 ok，因为都包含值方法集
- 指针方法集和接口匹配
- 只能将指针对象赋值给接口变量，因为只有指针方法集和接口匹配
- 如果将值对象赋值给接口变量，会在编译期报错 (会触发接口合理性检查机制)
为啥 i = s2Val 会报错，因为值方法集和接口不匹配。
### 零值 Mutex 是有效的
零值 `sync.Mutex` 和 `sync.RWMutex` 是有效的。所以指向 mutex 的指针基本是不必要的。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
mu := new(sync.Mutex)
mu.Lock()
```
</td><td>
```go
var mu sync.Mutex
mu.Lock()
```
</td></tr>
</tbody></table>
如果你使用结构体指针，mutex 应该作为结构体的非指针字段。即使该结构体不被导出，也不要直接把 mutex 嵌入到结构体中。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
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]
}
```
</td><td>
```go
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]
}
```
</td></tr>
<tr><td>
`Mutex` 字段，`Lock` 和 `Unlock` 方法是 `SMap` 导出的 API 中不刻意说明的一部分。
</td><td>
mutex 及其方法是 `SMap` 的实现细节，对其调用者不可见。
</td></tr>
</tbody></table>
### 在边界处拷贝 Slices 和 Maps
slices 和 maps 包含了指向底层数据的指针，因此在需要复制它们时要特别注意。
#### 接收 Slices 和 Maps
请记住，当 map 或 slice 作为函数参数传入时，如果您存储了对它们的引用，则用户可以对其进行修改。
<table>
<thead><tr><th>Bad</th> <th>Good</th></tr></thead>
<tbody>
<tr>
<td>
```go
func (d *Driver) SetTrips(trips []Trip) {
d.trips = trips
}
trips := ...
d1.SetTrips(trips)
// 你是要修改 d1.trips 吗？
trips[0] = ...
```
</td>
<td>
```go
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] = ...
```
</td>
</tr>
</tbody>
</table>
#### 返回 slices 或 maps
同样，请注意用户对暴露内部状态的 map 或 slice 的修改。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Stats struct {
mu sync.Mutex
counters map[string]int
}
// Snapshot 返回当前状态。
func (s *Stats) Snapshot() map[string]int {
s.mu.Lock()
defer s.mu.Unlock()
return s.counters
}
// snapshot 不再受互斥锁保护
// 因此对 snapshot 的任何访问都将受到数据竞争的影响
// 影响 stats.counters
snapshot := stats.Snapshot()
```
</td><td>
```go
type Stats struct {
mu sync.Mutex
counters map[string]int
}
func (s *Stats) Snapshot() map[string]int {
s.mu.Lock()
defer s.mu.Unlock()
result := make(map[string]int, len(s.counters))
for k, v := range s.counters {
result[k] = v
}
return result
}
// snapshot 现在是一个拷贝
snapshot := stats.Snapshot()
```
</td></tr>
</tbody></table>
### 使用 defer 释放资源
使用 defer 释放资源，诸如文件和锁。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
p.Lock()
if p.count < 10 {
p.Unlock()
return p.count
}
p.count++
newCount := p.count
p.Unlock()
return newCount
// 当有多个 return 分支时，很容易遗忘 unlock
```
</td><td>
```go
p.Lock()
defer p.Unlock()
if p.count < 10 {
return p.count
}
p.count++
return p.count
// 更可读
```
</td></tr>
</tbody></table>
Defer 的开销非常小，只有在您可以证明函数执行时间处于纳秒级的程度时，才应避免这样做。使用 defer 提升可读性是值得的，因为使用它们的成本微不足道。尤其适用于那些不仅仅是简单内存访问的较大的方法，在这些方法中其他计算的资源消耗远超过 `defer`。
### Channel 的 size 要么是 1，要么是无缓冲的
channel 通常 size 应为 1 或是无缓冲的。默认情况下，channel 是无缓冲的，其 size 为零。任何其他尺寸都必须经过严格的审查。我们需要考虑如何确定大小，考虑是什么阻止了 channel 在高负载下和阻塞写时的写入，以及当这种情况发生时系统逻辑有哪些变化。(翻译解释：按照原文意思是需要界定通道边界，竞态条件，以及逻辑上下文梳理)
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// 应该足以满足任何情况！
c := make(chan int, 64)
```
</td><td>
```go
// 大小：1
c := make(chan int, 1) // 或者
// 无缓冲 channel，大小为 0
c := make(chan int)
```
</td></tr>
</tbody></table>
### 枚举从 1 开始
在 Go 中引入枚举的标准方法是声明一个自定义类型和一个使用了 iota 的 const 组。由于变量的默认值为 0，因此通常应以非零值开头枚举。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Operation int
const (
Add Operation = iota
Subtract
Multiply
)
// Add=0, Subtract=1, Multiply=2
```
</td><td>
```go
type Operation int
const (
Add Operation = iota + 1
Subtract
Multiply
)
// Add=1, Subtract=2, Multiply=3
```
</td></tr>
</tbody></table>
在某些情况下，使用零值是有意义的（枚举从零开始），例如，当零值是理想的默认行为时。
```go
type LogOutput int
const (
LogToStdout LogOutput = iota
LogToFile
LogToRemote
)
// LogToStdout=0, LogToFile=1, LogToRemote=2
```
### 使用 time 处理时间
时间处理很复杂。关于时间的错误假设通常包括以下几点。
1. 一天有 24 小时
2. 一小时有 60 分钟
3. 一周有七天
4. 一年 365 天
5. [还有更多](https://infiniteundo.com/post/25326999628/falsehoods-programmers-believe-about-time)
例如，*1* 表示在一个时间点上加上 24 小时并不总是产生一个新的日历日。
因此，在处理时间时始终使用 [`"time"`] 包，因为它有助于以更安全、更准确的方式处理这些不正确的假设。
[`"time"`]: https://pkg.go.dev/time/
#### 使用 `time.Time` 表达瞬时时间
在处理时间的瞬间时使用 [`time.Time`]，在比较、添加或减去时间时使用 `time.Time` 中的方法。
[`time.Time`]: https://pkg.go.dev/time/#Time
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func isActive(now, start, stop int) bool {
return start <= now && now < stop
}
```
</td><td>
```go
func isActive(now, start, stop time.Time) bool {
return (start.Before(now) || start.Equal(now)) && now.Before(stop)
}
```
</td></tr>
</tbody></table>
#### 使用 `time.Duration` 表达时间段
在处理时间段时使用 [`time.Duration`] .
[`time.Duration`]: https://pkg.go.dev/time/#Duration
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func poll(delay int) {
for {
// ...
time.Sleep(time.Duration(delay) * time.Millisecond)
}
}
poll(10) // 是几秒钟还是几毫秒？
```
</td><td>
```go
func poll(delay time.Duration) {
for {
// ...
time.Sleep(delay)
}
}
poll(10*time.Second)
```
</td></tr>
</tbody></table>
回到第一个例子，在一个时间瞬间加上 24 小时，我们用于添加时间的方法取决于意图。如果我们想要下一个日历日 (当前天的下一天) 的同一个时间点，我们应该使用 [`Time.AddDate`]。但是，如果我们想保证某一时刻比前一时刻晚 24 小时，我们应该使用 [`Time.Add`]。
[`Time.AddDate`]: https://pkg.go.dev/time/#Time.AddDate
[`Time.Add`]: https://pkg.go.dev/time/#Time.Add
```go
newDay := t.AddDate(0 /* years */, 0 /* months */, 1 /* days */)
maybeNewDay := t.Add(24 * time.Hour)
```
#### 对外部系统使用 `time.Time` 和 `time.Duration`
尽可能在与外部系统的交互中使用 `time.Duration` 和 `time.Time` 例如 :
- Command-line 标志：[`flag`] 通过 [`time.ParseDuration`] 支持 `time.Duration`
- JSON: [`encoding/json`] 通过其 [`UnmarshalJSON` method] 方法支持将 `time.Time` 编码为 [RFC 3339] 字符串
- SQL: [`database/sql`] 支持将 `DATETIME` 或 `TIMESTAMP` 列转换为 `time.Time`，如果底层驱动程序支持则返回
- YAML: [`gopkg.in/yaml.v2`] 支持将 `time.Time` 作为 [RFC 3339] 字符串，并通过 [`time.ParseDuration`] 支持 `time.Duration`。
[`flag`]: https://pkg.go.dev/flag/
[`time.ParseDuration`]: https://pkg.go.dev/time/#ParseDuration
[`encoding/json`]: https://pkg.go.dev/encoding/json/
[RFC 3339]: https://tools.ietf.org/html/rfc3339
[`UnmarshalJSON` method]: https://pkg.go.dev/time/#Time.UnmarshalJSON
[`database/sql`]: https://pkg.go.dev/database/sql/
[`gopkg.in/yaml.v2`]: https://pkg.go.dev/gopkg.in/yaml.v2
当不能在这些交互中使用 `time.Duration` 时，请使用 `int` 或 `float64`，并在字段名称中包含单位。
例如，由于 `encoding/json` 不支持 `time.Duration`，因此该单位包含在字段的名称中。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// {"interval": 2}
type Config struct {
Interval int `json:"interval"`
}
```
</td><td>
```go
// {"intervalMillis": 2000}
type Config struct {
IntervalMillis int `json:"intervalMillis"`
}
```
</td></tr>
</tbody></table>
当在这些交互中不能使用 `time.Time` 时，除非达成一致，否则使用 `string` 和 [RFC 3339] 中定义的格式时间戳。默认情况下，[`Time.UnmarshalText`] 使用此格式，并可通过 [`time.RFC3339`] 在 `Time.Format` 和 `time.Parse` 中使用。
[`Time.UnmarshalText`]: https://pkg.go.dev/time/#Time.UnmarshalText
[`time.RFC3339`]: https://pkg.go.dev/time/#RFC3339
尽管这在实践中并不成问题，但请记住，`"time"` 包不支持解析闰秒时间戳（[8728]），也不在计算中考虑闰秒（[15190]）。如果您比较两个时间瞬间，则差异将不包括这两个瞬间之间可能发生的闰秒。
[8728]: https://go.dev/issues/8728
[15190]: https://go.dev/issues/15190
<!-- TODO: section on String methods for enums -->
### Errors
#### 错误类型
声明错误的选项很少。
在选择最适合您的用例的选项之前，请考虑以下事项。
- 调用者是否需要匹配错误以便他们可以处理它？
如果是，我们必须通过声明顶级错误变量或自定义类型来支持 [`errors.Is`] 或 [`errors.As`] 函数。
- 错误消息是否为静态字符串，还是需要上下文信息的动态字符串？
如果是静态字符串，我们可以使用 [`errors.New`]，但对于后者，我们必须使用 [`fmt.Errorf`] 或自定义错误类型。
- 我们是否正在传递由下游函数返回的新错误？
如果是这样，请参阅[错误包装部分](#错误包装)。
[`errors.Is`]: https://pkg.go.dev/errors/#Is
[`errors.As`]: https://pkg.go.dev/errors/#As
| 错误匹配？| 错误消息 | 指导 |
|-----------------|---------------|-------------------------------------|
| No | static | [`errors.New`] |
| No | dynamic | [`fmt.Errorf`] |
| Yes | static | top-level `var` with [`errors.New`] |
| Yes | dynamic | custom `error` type |
[`errors.New`]: https://pkg.go.dev/errors/#New
[`fmt.Errorf`]: https://pkg.go.dev/fmt/#Errorf
例如，
使用 [`errors.New`] 表示带有静态字符串的错误。
如果调用者需要匹配并处理此错误，则将此错误导出为变量以支持将其与 `errors.Is` 匹配。
<table>
<thead><tr><th>无错误匹配</th><th>错误匹配</th></tr></thead>
<tbody>
<tr><td>
```go
// package foo
func Open() error {
return errors.New("could not open")
}
// package bar
if err := foo.Open(); err != nil {
// Can't handle the error.
panic("unknown error")
}
```
</td><td>
```go
// package foo
var ErrCouldNotOpen = errors.New("could not open")
func Open() error {
return ErrCouldNotOpen
}
// package bar
if err := foo.Open(); err != nil {
if errors.Is(err, foo.ErrCouldNotOpen) {
// handle the error
} else {
panic("unknown error")
}
}
```
</td></tr>
</tbody></table>
对于动态字符串的错误，
如果调用者不需要匹配它，则使用 [`fmt.Errorf`]，
如果调用者确实需要匹配它，则自定义 `error`。
<table>
<thead><tr><th>无错误匹配</th><th>错误匹配</th></tr></thead>
<tbody>
<tr><td>
```go
// package foo
func Open(file string) error {
return fmt.Errorf("file %q not found", file)
}
// package bar
if err := foo.Open("testfile.txt"); err != nil {
// Can't handle the error.
panic("unknown error")
}
```
</td><td>
```go
// package foo
type NotFoundError struct {
File string
}
func (e *NotFoundError) Error() string {
return fmt.Sprintf("file %q not found", e.File)
}
func Open(file string) error {
return &NotFoundError{File: file}
}
// package bar
if err := foo.Open("testfile.txt"); err != nil {
var notFound *NotFoundError
if errors.As(err, ¬Found) {
// handle the error
} else {
panic("unknown error")
}
}
```
</td></tr>
</tbody></table>
请注意，如果您从包中导出错误变量或类型，
它们将成为包的公共 API 的一部分。
#### 错误包装
如果调用其他方法时出现错误，通常有三种处理方式可以选择：
- 将原始错误原样返回
- 使用 `fmt.Errorf` 搭配 `%w` 将错误添加进上下文后返回
- 使用 `fmt.Errorf` 搭配 `%v` 将错误添加进上下文后返回
如果没有要添加的其他上下文，则按原样返回原始错误。
这将保留原始错误类型和消息。
这非常适合底层错误消息有足够的信息来追踪它来自哪里的错误。
否则，尽可能在错误消息中添加上下文
这样就不会出现诸如“连接被拒绝”之类的模糊错误，
您会收到更多有用的错误，例如“调用服务 foo：连接被拒绝”。
使用 `fmt.Errorf` 为你的错误添加上下文，
根据调用者是否应该能够匹配和提取根本原因，在 `%w` 或 `%v` 动词之间进行选择。
- 如果调用者应该可以访问底层错误，请使用 `%w`。
对于大多数包装错误，这是一个很好的默认值，
但请注意，调用者可能会开始依赖此行为。因此，对于包装错误是已知`var`或类型的情况，请将其作为函数契约的一部分进行记录和测试。
- 使用 `%v` 来混淆底层错误。
调用者将无法匹配它，但如果需要，您可以在将来切换到 `%w`。
在为返回的错误添加上下文时，通过避免使用"failed to"之类的短语来保持上下文简洁，当错误通过堆栈向上渗透时，它会一层一层被堆积起来：
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
s, err := store.New()
if err != nil {
return fmt.Errorf(
"failed to create new store: %w", err)
}
```
</td><td>
```go
s, err := store.New()
if err != nil {
return fmt.Errorf(
"new store: %w", err)
}
```
</td></tr><tr><td>
```plain
failed to x: failed to y: failed to create new store: the error
```
</td><td>
```plain
x: y: new store: the error
```
</td></tr>
</tbody></table>
然而，一旦错误被发送到另一个系统，应该清楚消息是一个错误（例如`err` 标签或日志中的"Failed"前缀）。
另见 [不要只检查错误，优雅地处理它们]。
[`"pkg/errors".Cause`]: https://pkg.go.dev/github.com/pkg/errors#Cause
[不要只检查错误，优雅地处理它们]: https://dave.cheney.net/2016/04/27/dont-just-check-errors-handle-them-gracefully
#### 错误命名
对于存储为全局变量的错误值，
根据是否导出，使用前缀 `Err` 或 `err`。
请看指南 [对于未导出的顶层常量和变量，使用_作为前缀](#对于未导出的顶层常量和变量使用_作为前缀)。
```go
var (
// 导出以下两个错误，以便此包的用户可以将它们与 errors.Is 进行匹配。
ErrBrokenLink = errors.New("link is broken")
ErrCouldNotOpen = errors.New("could not open")
// 这个错误没有被导出，因为我们不想让它成为我们公共 API 的一部分。我们可能仍然在带有错误的包内使用它。
errNotFound = errors.New("not found")
)
```
对于自定义错误类型，请改用后缀 `Error`。
```go
// 同样，这个错误被导出，以便这个包的用户可以将它与 errors.As 匹配。
type NotFoundError struct {
File string
}
func (e *NotFoundError) Error() string {
return fmt.Sprintf("file %q not found", e.File)
}
// 并且这个错误没有被导出，因为我们不想让它成为公共 API 的一部分。我们仍然可以在带有 errors.As 的包中使用它。
type resolveError struct {
Path string
}
func (e *resolveError) Error() string {
return fmt.Sprintf("resolve %q", e.Path)
}
```
#### 一次处理错误
当调用方从被调用方接收到错误时，它可以根据对错误的了解，以各种不同的方式进行处理。
其中包括但不限于：
- 如果被调用者约定定义了特定的错误，则将错误与`errors.Is`或`errors.As`匹配，并以不同的方式处理分支
- 如果错误是可恢复的，则记录错误并正常降级
- 如果该错误表示特定于域的故障条件，则返回定义明确的错误
- 返回错误，无论是 [wrapped](#错误包装) 还是逐字逐句
无论调用方如何处理错误，它通常都应该只处理每个错误一次。例如，调用方不应该记录错误然后返回，因为*its*调用方也可能处理错误。
例如，考虑以下情况：
<table>
<thead><tr><th>Description</th><th>Code</th></tr></thead>
<tbody>
<tr><td>
**Bad**: 记录错误并将其返回
堆栈中的调用程序可能会对该错误采取类似的操作。这样做会在应用程序日志中造成大量噪音，但收效甚微。
</td><td>
```go
u, err := getUser(id)
if err != nil {
// BAD: See description
log.Printf("Could not get user %q: %v", id, err)
return err
}
```
</td></tr>
<tr><td>
**Good**: 将错误换行并返回
堆栈中更靠上的调用程序将处理该错误。使用`%w`可确保它们可以将错误与`errors.Is`或`errors.As`相匹配（如果相关）。
</td><td>
```go
u, err := getUser(id)
if err != nil {
return fmt.Errorf("get user %q: %w", id, err)
}
```
</td></tr>
<tr><td>
**Good**: 记录错误并正常降级
如果操作不是绝对必要的，我们可以通过从中恢复来提供降级但不间断的体验。
</td><td>
```go
if err := emitMetrics(); err != nil {
// Failure to write metrics should not
// break the application.
log.Printf("Could not emit metrics: %v", err)
}
```
</td></tr>
<tr><td>
**Good**: 匹配错误并适当降级
如果被调用者在其约定中定义了一个特定的错误，并且失败是可恢复的，则匹配该错误案例并正常降级。对于所有其他案例，请包装错误并返回。
堆栈中更靠上的调用程序将处理其他错误。
</td><td>
```go
tz, err := getUserTimeZone(id)
if err != nil {
if errors.Is(err, ErrUserNotFound) {
// User doesn't exist. Use UTC.
tz = time.UTC
} else {
return fmt.Errorf("get user %q: %w", id, err)
}
}
```
</td></tr>
</tbody></table>
### 处理断言失败
[类型断言] 将会在检测到不正确的类型时，以单一返回值形式返回 panic。因此，请始终使用“逗号 ok”习语。
[类型断言]: https://golang.org/ref/spec#Type_assertions
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
t := i.(string)
```
</td><td>
```go
t, ok := i.(string)
if !ok {
// 优雅地处理错误
}
```
</td></tr>
</tbody></table>
<!-- TODO: There are a few situations where the single assignment form is
fine. -->
### 不要使用 panic
在生产环境中运行的代码必须避免出现 panic。panic 是 [级联失败] 的主要根源。如果发生错误，该函数必须返回错误，并允许调用方决定如何处理它。
[级联失败]: https://en.wikipedia.org/wiki/Cascading_failure
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func run(args []string) {
if len(args) == 0 {
panic("an argument is required")
}
// ...
}
func main() {
run(os.Args[1:])
}
```
</td><td>
```go
func run(args []string) error {
if len(args) == 0 {
return errors.New("an argument is required")
}
// ...
return nil
}
func main() {
if err := run(os.Args[1:]); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
```
</td></tr>
</tbody></table>
panic/recover 不是错误处理策略。仅当发生不可恢复的事情（例如：nil 引用）时，程序才必须 panic。程序初始化是一个例外：程序启动时应使程序中止的不良情况可能会引起 panic。
```go
var _statusTemplate = template.Must(template.New("name").Parse("_statusHTML"))
```
即使在测试代码中，也优先使用`t.Fatal`或者`t.FailNow`而不是 panic 来确保失败被标记。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// func TestFoo(t *testing.T)
f, err := os.CreateTemp("", "test")
if err != nil {
panic("failed to set up test")
}
```
</td><td>
```go
// func TestFoo(t *testing.T)
f, err := os.CreateTemp("", "test")
if err != nil {
t.Fatal("failed to set up test")
}
```
</td></tr>
</tbody></table>
<!-- TODO: Explain how to use _test packages. -->
### 使用 go.uber.org/atomic
使用 [sync/atomic] 包的原子操作对原始类型 (`int32`, `int64`等）进行操作，因为很容易忘记使用原子操作来读取或修改变量。
[go.uber.org/atomic] 通过隐藏基础类型为这些操作增加了类型安全性。此外，它包括一个方便的`atomic.Bool`类型。
[go.uber.org/atomic]: https://pkg.go.dev/go.uber.org/atomic
[sync/atomic]: https://pkg.go.dev/sync/atomic/
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
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!
}
```
</td><td>
```go
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()
}
```
</td></tr>
</tbody></table>
### 避免可变全局变量
使用选择依赖注入方式避免改变全局变量。
既适用于函数指针又适用于其他值类型
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// sign.go
var _timeNow = time.Now
func sign(msg string) string {
now := _timeNow()
return signWithTime(msg, now)
}
```
</td><td>
```go
// sign.go
type signer struct {
now func() time.Time
}
func newSigner() *signer {
return &signer{
now: time.Now,
}
}
func (s *signer) Sign(msg string) string {
now := s.now()
return signWithTime(msg, now)
}
```
</td></tr>
<tr><td>
```go
// sign_test.go
func TestSign(t *testing.T) {
oldTimeNow := _timeNow
_timeNow = func() time.Time {
return someFixedTime
}
defer func() { _timeNow = oldTimeNow }()
assert.Equal(t, want, sign(give))
}
```
</td><td>
```go
// sign_test.go
func TestSigner(t *testing.T) {
s := newSigner()
s.now = func() time.Time {
return someFixedTime
}
assert.Equal(t, want, s.Sign(give))
}
```
</td></tr>
</tbody></table>
### 避免在公共结构中嵌入类型
这些嵌入的类型泄漏实现细节、禁止类型演化和模糊的文档。
假设您使用共享的 `AbstractList` 实现了多种列表类型，请避免在具体的列表实现中嵌入 `AbstractList`。
相反，只需手动将方法写入具体的列表，该列表将委托给抽象列表。
```go
type AbstractList struct {}
// 添加将实体添加到列表中。
func (l *AbstractList) Add(e Entity) {
// ...
}
// 移除从列表中移除实体。
func (l *AbstractList) Remove(e Entity) {
// ...
}
```
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// ConcreteList 是一个实体列表。
type ConcreteList struct {
*AbstractList
}
```
</td><td>
```go
// ConcreteList 是一个实体列表。
type ConcreteList struct {
list *AbstractList
}
// 添加将实体添加到列表中。
func (l *ConcreteList) Add(e Entity) {
l.list.Add(e)
}
// 移除从列表中移除实体。
func (l *ConcreteList) Remove(e Entity) {
l.list.Remove(e)
}
```
</td></tr>
</tbody></table>
Go 允许 [类型嵌入](https://golang.org/doc/effective_go.html#embedding) 作为继承和组合之间的折衷。外部类型获取嵌入类型的方法的隐式副本。默认情况下，这些方法委托给嵌入实例的同一方法。
结构还获得与类型同名的字段。
所以，如果嵌入的类型是 public，那么字段是 public。为了保持向后兼容性，外部类型的每个未来版本都必须保留嵌入类型。
很少需要嵌入类型。
这是一种方便，可以帮助您避免编写冗长的委托方法。
即使嵌入兼容的抽象列表 *interface*，而不是结构体，这将为开发人员提供更大的灵活性来改变未来，但仍然泄露了具体列表使用抽象实现的细节。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// AbstractList 是各种实体列表的通用实现。
type AbstractList interface {
Add(Entity)
Remove(Entity)
}
// ConcreteList 是一个实体列表。
type ConcreteList struct {
AbstractList
}
```
</td><td>
```go
// ConcreteList 是一个实体列表。
type ConcreteList struct {
list AbstractList
}
// 添加将实体添加到列表中。
func (l *ConcreteList) Add(e Entity) {
l.list.Add(e)
}
// 移除从列表中移除实体。
func (l *ConcreteList) Remove(e Entity) {
l.list.Remove(e)
}
```
</td></tr>
</tbody></table>
无论是使用嵌入结构还是嵌入接口，都会限制类型的演化。
- 向嵌入接口添加方法是一个破坏性的改变。
- 从嵌入结构体删除方法是一个破坏性改变。
- 删除嵌入类型是一个破坏性的改变。
- 即使使用满足相同接口的类型替换嵌入类型，也是一个破坏性的改变。
尽管编写这些委托方法是乏味的，但是额外的工作隐藏了实现细节，留下了更多的更改机会，还消除了在文档中发现完整列表接口的间接性操作。
### 避免使用内置名称
Go [语言规范] 概述了几个内置的，
不应在 Go 项目中使用的 [预先声明的标识符]。
根据上下文的不同，将这些标识符作为名称重复使用，
将在当前作用域（或任何嵌套作用域）中隐藏原始标识符，或者混淆代码。
在最好的情况下，编译器会报错；在最坏的情况下，这样的代码可能会引入潜在的、难以恢复的错误。
[语言规范]: https://golang.org/ref/spec
[预先声明的标识符]: https://golang.org/ref/spec#Predeclared_identifiers
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
var error string
// `error` 作用域隐式覆盖
// or
func handleErrorMessage(error string) {
// `error` 作用域隐式覆盖
}
```
</td><td>
```go
var errorMessage string
// `error` 指向内置的非覆盖
// or
func handleErrorMessage(msg string) {
// `error` 指向内置的非覆盖
}
```
</td></tr>
<tr><td>
```go
type Foo struct {
// 虽然这些字段在技术上不构成阴影，但`error`或`string`字符串的重映射现在是不明确的。
error error
string string
}
func (f Foo) Error() error {
// `error` 和 `f.error` 在视觉上是相似的
return f.error
}
func (f Foo) String() string {
// `string` and `f.string` 在视觉上是相似的
return f.string
}
```
</td><td>
```go
type Foo struct {
// `error` and `string` 现在是明确的。
err error
str string
}
func (f Foo) Error() error {
return f.err
}
func (f Foo) String() string {
return f.str
}
```
</td></tr>
</tbody></table>
注意，编译器在使用预先分隔的标识符时不会生成错误，
但是诸如`go vet`之类的工具会正确地指出这些和其他情况下的隐式问题。
### 避免使用 `init()`
尽可能避免使用`init()`。当`init()`是不可避免或可取的，代码应先尝试：
1. 无论程序环境或调用如何，都要完全确定。
2. 避免依赖于其他`init()`函数的顺序或副作用。虽然`init()`顺序是明确的，但代码可以更改，
因此`init()`函数之间的关系可能会使代码变得脆弱和容易出错。
3. 避免访问或操作全局或环境状态，如机器信息、环境变量、工作目录、程序参数/输入等。
4. 避免`I/O`，包括文件系统、网络和系统调用。
不能满足这些要求的代码可能属于要作为`main()`调用的一部分（或程序生命周期中的其他地方），
或者作为`main()`本身的一部分写入。特别是，打算由其他程序使用的库应该特别注意完全确定性，
而不是执行“init magic”
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Foo struct {
// ...
}
var _defaultFoo Foo
func init() {
_defaultFoo = Foo{
// ...
}
}
```
</td><td>
```go
var _defaultFoo = Foo{
// ...
}
// or，为了更好的可测试性：
var _defaultFoo = defaultFoo()
func defaultFoo() Foo {
return Foo{
// ...
}
}
```
</td></tr>
<tr><td>
```go
type Config struct {
// ...
}
var _config Config
func init() {
// Bad: 基于当前目录
cwd, _ := os.Getwd()
// Bad: I/O
raw, _ := os.ReadFile(
path.Join(cwd, "config", "config.yaml"),
)
yaml.Unmarshal(raw, &_config)
}
```
</td><td>
```go
type Config struct {
// ...
}
func loadConfig() Config {
cwd, err := os.Getwd()
// handle err
raw, err := os.ReadFile(
path.Join(cwd, "config", "config.yaml"),
)
// handle err
var config Config
yaml.Unmarshal(raw, &config)
return config
}
```
</td></tr>
</tbody></table>
考虑到上述情况，在某些情况下，`init()`可能更可取或是必要的，可能包括：
- 不能表示为单个赋值的复杂表达式。
- 可插入的钩子，如`database/sql`、编码类型注册表等。
- 对 [Google Cloud Functions] 和其他形式的确定性预计算的优化。
[Google Cloud Functions]: https://cloud.google.com/functions/docs/bestpractices/tips#use_global_variables_to_reuse_objects_in_future_invocations
### 追加时优先指定切片容量
追加时优先指定切片容量
在尽可能的情况下，在初始化要追加的切片时为`make()`提供一个容量值。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
for n := 0; n < b.N; n++ {
data := make([]int, 0)
for k := 0; k < size; k++{
data = append(data, k)
}
}
```
</td><td>
```go
for n := 0; n < b.N; n++ {
data := make([]int, 0, size)
for k := 0; k < size; k++{
data = append(data, k)
}
}
```
</td></tr>
<tr><td>
```
BenchmarkBad-4 100000000 2.48s
```
</td><td>
```
BenchmarkGood-4 100000000 0.21s
```
</td></tr>
</tbody></table>
### 主函数退出方式 (Exit)
Go 程序使用 [`os.Exit`] 或者 [`log.Fatal*`] 立即退出 (使用`panic`不是退出程序的好方法，请 [不要使用 panic](#不要使用-panic)。)
[`os.Exit`]: https://pkg.go.dev/os/#Exit
[`log.Fatal*`]: https://pkg.go.dev/log/#Fatal
**仅在`main()`** 中调用其中一个 `os.Exit` 或者 `log.Fatal*`。所有其他函数应将错误返回到信号失败中。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func main() {
body := readFile(path)
fmt.Println(body)
}
func readFile(path string) string {
f, err := os.Open(path)
if err != nil {
log.Fatal(err)
}
b, err := os.ReadAll(f)
if err != nil {
log.Fatal(err)
}
return string(b)
}
```
</td><td>
```go
func main() {
body, err := readFile(path)
if err != nil {
log.Fatal(err)
}
fmt.Println(body)
}
func readFile(path string) (string, error) {
f, err := os.Open(path)
if err != nil {
return "", err
}
b, err := os.ReadAll(f)
if err != nil {
return "", err
}
return string(b), nil
}
```
</td></tr>
</tbody></table>
原则上：退出的具有多种功能的程序存在一些问题：
- 不明显的控制流：任何函数都可以退出程序，因此很难对控制流进行推理。
- 难以测试：退出程序的函数也将退出调用它的测试。这使得函数很难测试，并引入了跳过 `go test` 尚未运行的其他测试的风险。
- 跳过清理：当函数退出程序时，会跳过已经进入`defer`队列里的函数调用。这增加了跳过重要清理任务的风险。
#### 一次性退出
如果可能的话，你的`main（）`函数中 **最多一次** 调用 `os.Exit`或者`log.Fatal`。如果有多个错误场景停止程序执行，请将该逻辑放在单独的函数下并从中返回错误。
这会缩短 `main()` 函数，并将所有关键业务逻辑放入一个单独的、可测试的函数中。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
package main
func main() {
args := os.Args[1:]
if len(args) != 1 {
log.Fatal("missing file")
}
name := args[0]
f, err := os.Open(name)
if err != nil {
log.Fatal(err)
}
defer f.Close()
// 如果我们调用 log.Fatal 在这条线之后
// f.Close 将会被执行。
b, err := os.ReadAll(f)
if err != nil {
log.Fatal(err)
}
// ...
}
```
</td><td>
```go
package main
func main() {
if err := run(); err != nil {
log.Fatal(err)
}
}
func run() error {
args := os.Args[1:]
if len(args) != 1 {
return errors.New("missing file")
}
name := args[0]
f, err := os.Open(name)
if err != nil {
return err
}
defer f.Close()
b, err := os.ReadAll(f)
if err != nil {
return err
}
// ...
}
```
</td></tr>
</tbody></table>
上面的示例使用`log.Fatal`，但该指南也适用于`os.Exit`或任何调用`os.Exit`的库代码。
```go
func main() {
if err := run(); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
```
您可以根据需要更改`run()`的签名。例如，如果您的程序必须使用特定的失败退出代码退出，`run()`可能会返回退出代码而不是错误。这也允许单元测试直接验证此行为。
```go
func main() {
os.Exit(run(args))
}
func run() (exitCode int) {
// ...
}
```
请注意，这些示例中使用的`run()`函数并不是强制性的。
`run()`函数的名称、签名和设置具有灵活性。除其他外，您可以：
- 接受未分析的命令行参数 (e.g., `run(os.Args[1:])`)
- 解析`main()`中的命令行参数并将其传递到`run`
- 使用自定义错误类型将退出代码传回`main（）`
- 将业务逻辑置于不同的抽象层 `package main`
本指南只要求在`main()`中有一个位置负责实际的退出流程。
### 在序列化结构中使用字段标记
任何序列化到 JSON、YAML、，
或其他支持基于标记的字段命名的格式应使用相关标记进行注释。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Stock struct {
Price int
Name string
}
bytes, err := json.Marshal(Stock{
Price: 137,
Name: "UBER",
})
```
</td><td>
```go
type Stock struct {
Price int `json:"price"`
Name string `json:"name"`
// Safe to rename Name to Symbol.
}
bytes, err := json.Marshal(Stock{
Price: 137,
Name: "UBER",
})
```
</td></tr>
</tbody></table>
理论上：
结构的序列化形式是不同系统之间的契约。
对序列化表单结构（包括字段名）的更改会破坏此约定。在标记中指定字段名使约定明确，
它还可以通过重构或重命名字段来防止意外违反约定。
### 不要一劳永逸地使用 goroutine
Goroutines 是轻量级的，但它们不是免费的：
至少，它们会为堆栈和 CPU 的调度消耗内存。
虽然这些成本对于 Goroutines 的使用来说很小，但当它们在没有受控生命周期的情况下大量生成时会导致严重的性能问题。
具有非托管生命周期的 Goroutines 也可能导致其他问题，例如防止未使用的对象被垃圾回收并保留不再使用的资源。
因此，不要在代码中泄漏 goroutine。
使用 [go.uber.org/goleak](https://pkg.go.dev/go.uber.org/goleak)
来测试可能产生 goroutine 的包内的 goroutine 泄漏。
一般来说，每个 goroutine:
- 必须有一个可预测的停止运行时间；或者
- 必须有一种方法可以向 goroutine 发出信号它应该停止
在这两种情况下，都必须有一种方式代码来阻塞并等待 goroutine 完成。
For example:
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
go func() {
for {
flush()
time.Sleep(delay)
}
}()
```
</td><td>
```go
var (
stop = make(chan struct{}) // 告诉 goroutine 停止
done = make(chan struct{}) // 告诉我们 goroutine 退出了
)
go func() {
defer close(done)
ticker := time.NewTicker(delay)
defer ticker.Stop()
for {
select {
case <-tick.C:
flush()
case <-stop:
return
}
}
}()
// 其它...
close(stop) // 指示 goroutine 停止
<-done // and wait for it to exit
```
</td></tr>
<tr><td>
没有办法阻止这个 goroutine。这将一直运行到应用程序退出。
</td><td>
这个 goroutine 可以用 `close(stop)`,
我们可以等待它退出 `<-done`.
</td></tr>
</tbody></table>
#### 等待 goroutines 退出
给定一个由系统生成的 goroutine，
必须有一种方案能等待 goroutine 的退出。
有两种常用的方法可以做到这一点：
- 使用 `sync.WaitGroup`.
如果您要等待多个 goroutine，请执行此操作
```go
var wg sync.WaitGroup
for i := 0; i < N; i++ {
wg.Add(1)
go func() {
defer wg.Done()
// ...
}()
}
// To wait for all to finish:
wg.Wait()
```
- 添加另一个 `chan struct{}`，goroutine 完成后会关闭它。
如果只有一个 goroutine，请执行此操作。
```go
done := make(chan struct{})
go func() {
defer close(done)
// ...
}()
// To wait for the goroutine to finish:
<-done
```
#### 不要在 `init()` 使用 goroutines
`init()` 函数不应该产生 goroutines。
另请参阅 [避免使用 init()](#避免使用-init)。
如果一个包需要一个后台 goroutine，
它必须公开一个负责管理 goroutine 生命周期的对象。
该对象必须提供一个方法（`Close`、`Stop`、`Shutdown` 等）来指示后台 goroutine 停止并等待它的退出。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func init() {
go doWork()
}
func doWork() {
for {
// ...
}
}
```
</td><td>
```go
type Worker struct{ /* ... */ }
func NewWorker(...) *Worker {
w := &Worker{
stop: make(chan struct{}),
done: make(chan struct{}),
// ...
}
go w.doWork()
}
func (w *Worker) doWork() {
defer close(w.done)
for {
// ...
case <-w.stop:
return
}
}
// Shutdown 告诉 worker 停止
// 并等待它完成。
func (w *Worker) Shutdown() {
close(w.stop)
<-w.done
}
```
</td></tr>
<tr><td>
当用户导出这个包时，无条件地生成一个后台 goroutine。
用户无法控制 goroutine 或停止它的方法。
</td><td>
仅当用户请求时才生成工作人员。
提供一种关闭工作器的方法，以便用户可以释放工作器使用的资源。
请注意，如果工作人员管理多个 goroutine，则应使用`WaitGroup`。
请参阅 [等待 goroutines 退出](#等待-goroutines-退出)。
</td></tr>
</tbody></table>
## 性能
性能方面的特定准则只适用于高频场景。
### 优先使用 strconv 而不是 fmt
将原语转换为字符串或从字符串转换时，`strconv`速度比`fmt`快。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
for i := 0; i < b.N; i++ {
s := fmt.Sprint(rand.Int())
}
```
</td><td>
```go
for i := 0; i < b.N; i++ {
s := strconv.Itoa(rand.Int())
}
```
</td></tr>
<tr><td>
```plain
BenchmarkFmtSprint-4 143 ns/op 2 allocs/op
```
</td><td>
```plain
BenchmarkStrconv-4 64.2 ns/op 1 allocs/op
```
</td></tr>
</tbody></table>
### 避免字符串到字节的转换
不要反复从固定字符串创建字节 slice。相反，请执行一次转换并捕获结果。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
for i := 0; i < b.N; i++ {
w.Write([]byte("Hello world"))
}
```
</td><td>
```go
data := []byte("Hello world")
for i := 0; i < b.N; i++ {
w.Write(data)
}
```
</tr>
<tr><td>
```plain
BenchmarkBad-4 50000000 22.2 ns/op
```
</td><td>
```plain
BenchmarkGood-4 500000000 3.25 ns/op
```
</td></tr>
</tbody></table>
### 指定容器容量
尽可能指定容器容量，以便为容器预先分配内存。这将在添加元素时最小化后续分配（通过复制和调整容器大小）。
#### 指定 Map 容量提示
在尽可能的情况下，在使用 `make()` 初始化的时候提供容量信息
```go
make(map[T1]T2, hint)
```
向`make()`提供容量提示会在初始化时尝试调整 map 的大小，这将减少在将元素添加到 map 时为 map 重新分配内存。
注意，与 slices 不同。map 容量提示并不保证完全的、预先的分配，而是用于估计所需的 hashmap bucket 的数量。
因此，在将元素添加到 map 时，甚至在指定 map 容量时，仍可能发生分配。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
m := make(map[string]os.FileInfo)
files, _ := os.ReadDir("./files")
for _, f := range files {
m[f.Name()] = f
}
```
</td><td>
```go
files, _ := os.ReadDir("./files")
m := make(map[string]os.FileInfo, len(files))
for _, f := range files {
m[f.Name()] = f
}
```
</td></tr>
<tr><td>
`m` 是在没有大小提示的情况下创建的；在运行时可能会有更多分配。
</td><td>
`m` 是有大小提示创建的；在运行时可能会有更少的分配。
</td></tr>
</tbody></table>
#### 指定切片容量
在尽可能的情况下，在使用`make()`初始化切片时提供容量信息，特别是在追加切片时。
```go
make([]T, length, capacity)
```
与 maps 不同，slice capacity 不是一个提示：编译器将为提供给`make()`的 slice 的容量分配足够的内存，
这意味着后续的`append()`操作将导致零分配（直到 slice 的长度与容量匹配，在此之后，任何 append 都可能调整大小以容纳其他元素）。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
for n := 0; n < b.N; n++ {
data := make([]int, 0)
for k := 0; k < size; k++{
data = append(data, k)
}
}
```
</td><td>
```go
for n := 0; n < b.N; n++ {
data := make([]int, 0, size)
for k := 0; k < size; k++{
data = append(data, k)
}
}
```
</td></tr>
<tr><td>
```
BenchmarkBad-4 100000000 2.48s
```
</td><td>
```
BenchmarkGood-4 100000000 0.21s
```
</td></tr>
</tbody></table>
## 规范
### 避免过长的行
避免使用需要读者水平滚动或过度转动头部的代码行。
我们建议将行长度限制为 **99 characters** (99 个字符).
作者应该在达到这个限制之前换行，
但这不是硬性限制。
允许代码超过此限制。
### 一致性
本文中概述的一些标准都是客观性的评估，是根据场景、上下文、或者主观性的判断；
但是最重要的是，**保持一致**.
一致性的代码更容易维护、是更合理的、需要更少的学习成本、并且随着新的约定出现或者出现错误后更容易迁移、更新、修复 bug
相反，在一个代码库中包含多个完全不同或冲突的代码风格会导致维护成本开销、不确定性和认知偏差。所有这些都会直接导致速度降低、代码审查痛苦、而且增加 bug 数量。
将这些标准应用于代码库时，建议在 package（或更大）级别进行更改，子包级别的应用程序通过将多个样式引入到同一代码中，违反了上述关注点。
### 相似的声明放在一组
Go 语言支持将相似的声明放在一个组内。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
import "a"
import "b"
```
</td><td>
```go
import (
"a"
"b"
)
```
</td></tr>
</tbody></table>
这同样适用于常量、变量和类型声明：
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
const a = 1
const b = 2
var a = 1
var b = 2
type Area float64
type Volume float64
```
</td><td>
```go
const (
a = 1
b = 2
)
var (
a = 1
b = 2
)
type (
Area float64
Volume float64
)
```
</td></tr>
</tbody></table>
仅将相关的声明放在一组。不要将不相关的声明放在一组。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Operation int
const (
Add Operation = iota + 1
Subtract
Multiply
EnvVar = "MY_ENV"
)
```
</td><td>
```go
type Operation int
const (
Add Operation = iota + 1
Subtract
Multiply
)
const EnvVar = "MY_ENV"
```
</td></tr>
</tbody></table>
分组使用的位置没有限制，例如：你可以在函数内部使用它们：
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func f() string {
red := color.New(0xff0000)
green := color.New(0x00ff00)
blue := color.New(0x0000ff)
...
}
```
</td><td>
```go
func f() string {
var (
red = color.New(0xff0000)
green = color.New(0x00ff00)
blue = color.New(0x0000ff)
)
...
}
```
</td></tr>
</tbody></table>
例外：如果变量声明与其他变量相邻，则应将变量声明（尤其是函数内部的声明）分组在一起。对一起声明的变量执行此操作，即使它们不相关。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func (c *client) request() {
caller := c.name
format := "json"
timeout := 5*time.Second
var err error
// ...
}
```
</td><td>
```go
func (c *client) request() {
var (
caller = c.name
format = "json"
timeout = 5*time.Second
err error
)
// ...
}
```
</td></tr>
</tbody></table>
### import 分组
导入应该分为两组：
- 标准库
- 其他库
默认情况下，这是 goimports 应用的分组。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
import (
"fmt"
"os"
"go.uber.org/atomic"
"golang.org/x/sync/errgroup"
)
```
</td><td>
```go
import (
"fmt"
"os"
"go.uber.org/atomic"
"golang.org/x/sync/errgroup"
)
```
</td></tr>
</tbody></table>
### 包名
当命名包时，请按下面规则选择一个名称：
- 全部小写。没有大写或下划线。
- 大多数使用命名导入的情况下，不需要重命名。
- 简短而简洁。请记住，在每个使用的地方都完整标识了该名称。
- 不用复数。例如`net/url`，而不是`net/urls`。
- 不要用“common”，“util”，“shared”或“lib”。这些是不好的，信息量不足的名称。
另请参阅 [Go 包命名规则] 和 [Go 包样式指南].
[Go 包命名规则]: https://go.dev/blog/package-names
[Go 包样式指南]: https://rakyll.org/style-packages/
### 函数名
我们遵循 Go 社区关于使用 [MixedCaps 作为函数名] 的约定。有一个例外，为了对相关的测试用例进行分组，函数名可能包含下划线，如：`TestMyFunction_WhatIsBeingTested`.
[MixedCaps 作为函数名]: https://golang.org/doc/effective_go.html#mixed-caps
### 导入别名
如果程序包名称与导入路径的最后一个元素不匹配，则必须使用导入别名。
```go
import (
"net/http"
client "example.com/client-go"
trace "example.com/trace/v2"
)
```
在所有其他情况下，除非导入之间有直接冲突，否则应避免导入别名。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
import (
"fmt"
"os"
nettrace "golang.net/x/trace"
)
```
</td><td>
```go
import (
"fmt"
"os"
"runtime/trace"
nettrace "golang.net/x/trace"
)
```
</td></tr>
</tbody></table>
### 函数分组与顺序
- 函数应按粗略的调用顺序排序。
- 同一文件中的函数应按接收者分组。
因此，导出的函数应先出现在文件中，放在`struct`, `const`, `var`定义的后面。
在定义类型之后，但在接收者的其余方法之前，可能会出现一个 `newXYZ()`/`NewXYZ()`
由于函数是按接收者分组的，因此普通工具函数应在文件末尾出现。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
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{}
}
```
</td><td>
```go
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 {...}
```
</td></tr>
</tbody></table>
### 减少嵌套
代码应通过尽可能先处理错误情况/特殊情况并尽早返回或继续循环来减少嵌套。减少嵌套多个级别的代码的代码量。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
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)
}
}
```
</td><td>
```go
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()
}
```
</td></tr>
</tbody></table>
### 不必要的 else
如果在 if 的两个分支中都设置了变量，则可以将其替换为单个 if。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
var a int
if b {
a = 100
} else {
a = 10
}
```
</td><td>
```go
a := 10
if b {
a = 100
}
```
</td></tr>
</tbody></table>
### 顶层变量声明
在顶层，使用标准`var`关键字。请勿指定类型，除非它与表达式的类型不同。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
var _s string = F()
func F() string { return "A" }
```
</td><td>
```go
var _s = F()
// 由于 F 已经明确了返回一个字符串类型，因此我们没有必要显式指定_s 的类型
// 还是那种类型
func F() string { return "A" }
```
</td></tr>
</tbody></table>
如果表达式的类型与所需的类型不完全匹配，请指定类型。
```go
type myError struct{}
func (myError) Error() string { return "error" }
func F() myError { return myError{} }
var _e error = F()
// F 返回一个 myError 类型的实例，但是我们要 error 类型
```
### 对于未导出的顶层常量和变量，使用_作为前缀
在未导出的顶级`vars`和`consts`，前面加上前缀_，以使它们在使用时明确表示它们是全局符号。
基本依据：顶级变量和常量具有包范围作用域。使用通用名称可能很容易在其他文件中意外使用错误的值。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// 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.
}
```
</td><td>
```go
// foo.go
const (
_defaultPort = 8080
_defaultUser = "user"
)
```
</td></tr>
</tbody></table>
**例外**：未导出的错误值可以使用不带下划线的前缀 `err`。参见[错误命名](#错误命名)。
### 结构体中的嵌入
嵌入式类型（例如 mutex）应位于结构体内的字段列表的顶部，并且必须有一个空行将嵌入式字段与常规字段分隔开。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Client struct {
version int
http.Client
}
```
</td><td>
```go
type Client struct {
http.Client
version int
}
```
</td></tr>
</tbody></table>
内嵌应该提供切实的好处，比如以语义上合适的方式添加或增强功能。
它应该在对用户没有任何不利影响的情况下使用。（另请参见：[避免在公共结构中嵌入类型]）。
例外：即使在未导出类型中，Mutex 也不应该作为内嵌字段。另请参见：[零值 Mutex 是有效的]。
[避免在公共结构中嵌入类型]: #避免在公共结构中嵌入类型
[零值 Mutex 是有效的]: #零值-mutex-是有效的
嵌入 **不应该**:
- 纯粹是为了美观或方便。
- 使外部类型更难构造或使用。
- 影响外部类型的零值。如果外部类型有一个有用的零值，则在嵌入内部类型之后应该仍然有一个有用的零值。
- 作为嵌入内部类型的副作用，从外部类型公开不相关的函数或字段。
- 公开未导出的类型。
- 影响外部类型的复制形式。
- 更改外部类型的 API 或类型语义。
- 嵌入内部类型的非规范形式。
- 公开外部类型的实现详细信息。
- 允许用户观察或控制类型内部。
- 通过包装的方式改变内部函数的一般行为，这种包装方式会给用户带来一些意料之外情况。
简单地说，有意识地和有目的地嵌入。一种很好的测试体验是，
"是否所有这些导出的内部方法/字段都将直接添加到外部类型"
如果答案是`some`或`no`，不要嵌入内部类型 - 而是使用字段。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type A struct {
// Bad: A.Lock() and A.Unlock() 现在可用
// 不提供任何功能性好处，并允许用户控制有关 A 的内部细节。
sync.Mutex
}
```
</td><td>
```go
type countingWriteCloser struct {
// Good: Write() 在外层提供用于特定目的，
// 并且委托工作到内部类型的 Write() 中。
io.WriteCloser
count int
}
func (w *countingWriteCloser) Write(bs []byte) (int, error) {
w.count += len(bs)
return w.WriteCloser.Write(bs)
}
```
</td></tr>
<tr><td>
```go
type Book struct {
// Bad: 指针更改零值的有用性
io.ReadWriter
// other fields
}
// later
var b Book
b.Read(...) // panic: nil pointer
b.String() // panic: nil pointer
b.Write(...) // panic: nil pointer
```
</td><td>
```go
type Book struct {
// Good: 有用的零值
bytes.Buffer
// other fields
}
// later
var b Book
b.Read(...) // ok
b.String() // ok
b.Write(...) // ok
```
</td></tr>
<tr><td>
```go
type Client struct {
sync.Mutex
sync.WaitGroup
bytes.Buffer
url.URL
}
```
</td><td>
```go
type Client struct {
mtx sync.Mutex
wg sync.WaitGroup
buf bytes.Buffer
url url.URL
}
```
</td></tr>
</tbody></table>
### 本地变量声明
如果将变量明确设置为某个值，则应使用短变量声明形式 (`:=`)。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
var s = "foo"
```
</td><td>
```go
s := "foo"
```
</td></tr>
</tbody></table>
但是，在某些情况下，`var` 使用关键字时默认值会更清晰。例如，[声明空切片]。
[声明空切片]: https://go.dev/wiki/CodeReviewComments#declaring-empty-slices
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func f(list []int) {
filtered := []int{}
for _, v := range list {
if v > 10 {
filtered = append(filtered, v)
}
}
}
```
</td><td>
```go
func f(list []int) {
var filtered []int
for _, v := range list {
if v > 10 {
filtered = append(filtered, v)
}
}
}
```
</td></tr>
</tbody></table>
### nil 是一个有效的 slice
`nil` 是一个有效的长度为 0 的 slice，这意味着，
- 您不应明确返回长度为零的切片。应该返回`nil` 来代替。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
if x == "" {
return []int{}
}
```
</td><td>
```go
if x == "" {
return nil
}
```
</td></tr>
</tbody></table>
- 要检查切片是否为空，请始终使用`len(s) == 0`。而非 `nil`。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func isEmpty(s []string) bool {
return s == nil
}
```
</td><td>
```go
func isEmpty(s []string) bool {
return len(s) == 0
}
```
</td></tr>
</tbody></table>
- 零值切片（用`var`声明的切片）可立即使用，无需调用`make()`创建。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
nums := []int{}
// or, nums := make([]int)
if add1 {
nums = append(nums, 1)
}
if add2 {
nums = append(nums, 2)
}
```
</td><td>
```go
var nums []int
if add1 {
nums = append(nums, 1)
}
if add2 {
nums = append(nums, 2)
}
```
</td></tr>
</tbody></table>
记住，虽然 nil 切片是有效的切片，但它不等于长度为 0 的切片（一个为 nil，另一个不是），并且在不同的情况下（例如序列化），这两个切片的处理方式可能不同。
### 缩小变量作用域
如果有可能，尽量缩小变量作用范围。除非它与 [减少嵌套](#减少嵌套)的规则冲突。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
err := os.WriteFile(name, data, 0644)
if err != nil {
return err
}
```
</td><td>
```go
if err := os.WriteFile(name, data, 0644); err != nil {
return err
}
```
</td></tr>
</tbody></table>
如果需要在 if 之外使用函数调用的结果，则不应尝试缩小范围。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
if data, err := os.ReadFile(name); err == nil {
err = cfg.Decode(data)
if err != nil {
return err
}
fmt.Println(cfg)
return nil
} else {
return err
}
```
</td><td>
```go
data, err := os.ReadFile(name)
if err != nil {
return err
}
if err := cfg.Decode(data); err != nil {
return err
}
fmt.Println(cfg)
return nil
```
</td></tr>
</tbody></table>
### 避免参数语义不明确 (Avoid Naked Parameters)
函数调用中的`意义不明确的参数`可能会损害可读性。当参数名称的含义不明显时，请为参数添加 C 样式注释 (`/* ... */`)
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// func printInfo(name string, isLocal, done bool)
printInfo("foo", true, true)
```
</td><td>
```go
// func printInfo(name string, isLocal, done bool)
printInfo("foo", true /* isLocal */, true /* done */)
```
</td></tr>
</tbody></table>
对于上面的示例代码，还有一种更好的处理方式是将上面的 `bool` 类型换成自定义类型。将来，该参数可以支持不仅仅局限于两个状态（true/false）。
```go
type Region int
const (
UnknownRegion Region = iota
Local
)
type Status int
const (
StatusReady Status= iota + 1
StatusDone
// Maybe we will have a StatusInProgress in the future.
)
func printInfo(name string, region Region, status Status)
```
### 使用原始字符串字面值，避免转义
Go 支持使用 [原始字符串字面值](https://golang.org/ref/spec#raw_string_lit)，也就是 " ` " 来表示原生字符串，在需要转义的场景下，我们应该尽量使用这种方案来替换。
可以跨越多行并包含引号。使用这些字符串可以避免更难阅读的手工转义的字符串。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
wantError := "unknown name:\"test\""
```
</td><td>
```go
wantError := `unknown error:"test"`
```
</td></tr>
</tbody></table>
### 初始化结构体
#### 使用字段名初始化结构
初始化结构时，几乎应该始终指定字段名。目前由 [`go vet`] 强制执行。
[`go vet`]: https://golang.org/cmd/vet/
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
k := User{"John", "Doe", true}
```
</td><td>
```go
k := User{
FirstName: "John",
LastName: "Doe",
Admin: true,
}
```
</td></tr>
</tbody></table>
例外：当有 3 个或更少的字段时，测试表中的字段名可以省略。
```go
tests := []struct{
op Operation
want string
}{
{Add, "add"},
{Subtract, "subtract"},
}
```
#### 省略结构中的零值字段
初始化具有字段名的结构时，除非提供有意义的上下文，否则忽略值为零的字段。
也就是，让我们自动将这些设置为零值
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
user := User{
FirstName: "John",
LastName: "Doe",
MiddleName: "",
Admin: false,
}
```
</td><td>
```go
user := User{
FirstName: "John",
LastName: "Doe",
}
```
</td></tr>
</tbody></table>
这有助于通过省略该上下文中的默认值来减少阅读的障碍。只指定有意义的值。
在字段名提供有意义上下文的地方包含零值。例如，[表驱动测试](#表驱动测试) 中的测试用例可以受益于字段的名称，即使它们是零值的。
```go
tests := []struct{
give string
want int
}{
{give: "0", want: 0},
// ...
}
```
#### 对零值结构使用 `var`
如果在声明中省略了结构的所有字段，请使用 `var` 声明结构。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
user := User{}
```
</td><td>
```go
var user User
```
</td></tr>
</tbody></table>
这将零值结构与那些具有类似于为 [初始化 Maps](#初始化-maps) 创建的，区别于非零值字段的结构区分开来，
我们倾向于[声明一个空切片](https://go.dev/wiki/CodeReviewComments#declaring-empty-slices)
#### 初始化 Struct 引用
在初始化结构引用时，请使用`&T{}`代替`new(T)`，以使其与结构体初始化一致。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
sval := T{Name: "foo"}
// inconsistent
sptr := new(T)
sptr.Name = "bar"
```
</td><td>
```go
sval := T{Name: "foo"}
sptr := &T{Name: "bar"}
```
</td></tr>
</tbody></table>
### 初始化 Maps
对于空 map 请使用 `make(..)` 初始化，并且 map 是通过编程方式填充的。
这使得 map 初始化在表现上不同于声明，并且它还可以方便地在 make 后添加大小提示。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
var (
// m1 读写安全;
// m2 在写入时会 panic
m1 = map[T1]T2{}
m2 map[T1]T2
)
```
</td><td>
```go
var (
// m1 读写安全;
// m2 在写入时会 panic
m1 = make(map[T1]T2)
m2 map[T1]T2
)
```
</td></tr>
<tr><td>
声明和初始化看起来非常相似的。
</td><td>
声明和初始化看起来差别非常大。
</td></tr>
</tbody></table>
在尽可能的情况下，请在初始化时提供 map 容量大小，详细请看 [指定 Map 容量提示](#指定Map容量提示)。
另外，如果 map 包含固定的元素列表，则使用 map literals(map 初始化列表) 初始化映射。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
m := make(map[T1]T2, 3)
m[k1] = v1
m[k2] = v2
m[k3] = v3
```
</td><td>
```go
m := map[T1]T2{
k1: v1,
k2: v2,
k3: v3,
}
```
</td></tr>
</tbody></table>
基本准则是：在初始化时使用 map 初始化列表 来添加一组固定的元素。否则使用 `make` (如果可以，请尽量指定 map 容量)。
### 字符串 string format
如果你在函数外声明`Printf`-style 函数的格式字符串，请将其设置为`const`常量。
这有助于`go vet`对格式字符串执行静态分析。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
msg := "unexpected values %v, %v\n"
fmt.Printf(msg, 1, 2)
```
</td><td>
```go
const msg = "unexpected values %v, %v\n"
fmt.Printf(msg, 1, 2)
```
</td></tr>
</tbody></table>
### 命名 Printf 样式的函数
声明`Printf`-style 函数时，请确保`go vet`可以检测到它并检查格式字符串。
这意味着您应尽可能使用预定义的`Printf`-style 函数名称。`go vet`将默认检查这些。有关更多信息，请参见 [Printf 系列]。
[Printf 系列]: https://golang.org/cmd/vet/#hdr-Printf_family
如果不能使用预定义的名称，请以 f 结束选择的名称：`Wrapf`，而不是`Wrap`。`go vet`可以要求检查特定的 Printf 样式名称，但名称必须以`f`结尾。
```shell
go vet -printfuncs=wrapf,statusf
```
另请参阅 [go vet: Printf family check].
[go vet: Printf family check]: https://kuzminva.wordpress.com/2017/11/07/go-vet-printf-family-check/
## 编程模式
### 表驱动测试
当测试逻辑是重复的时候，通过 [subtests] 使用 table 驱动的方式编写 case 代码看上去会更简洁。
[subtests]: https://go.dev/blog/subtests
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// 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)
```
</td><td>
```go
// 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)
})
}
```
</td></tr>
</tbody></table>
很明显，使用 test table 的方式在代码逻辑扩展的时候，比如新增 test case，都会显得更加的清晰。
我们遵循这样的约定：将结构体切片称为`tests`。每个测试用例称为`tt`。此外，我们鼓励使用`give`和`want`前缀说明每个测试用例的输入和输出值。
```go
tests := []struct{
give string
wantHost string
wantPort string
}{
// ...
}
for _, tt := range tests {
// ...
}
```
并行测试，比如一些专门的循环（例如，生成 goroutine 或捕获引用作为循环体的一部分的那些循环）
必须注意在循环的范围内显式地分配循环变量，以确保它们保持预期的值。
```go
tests := []struct{
give string
// ...
}{
// ...
}
for _, tt := range tests {
tt := tt // for t.Parallel
t.Run(tt.give, func(t *testing.T) {
t.Parallel()
// ...
})
}
```
在上面的例子中，由于下面使用了`t.Parallel()`，我们必须声明一个作用域为循环迭代的`tt`变量。
如果我们不这样做，大多数或所有测试都会收到一个意外的`tt`值，或者一个在运行时发生变化的值。
### 功能选项
功能选项是一种模式，您可以在其中声明一个不透明 Option 类型，该类型在某些内部结构中记录信息。您接受这些选项的可变编号，并根据内部结构上的选项记录的全部信息采取行动。
将此模式用于您需要扩展的构造函数和其他公共 API 中的可选参数，尤其是在这些功能上已经具有三个或更多参数的情况下。
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// package db
func Open(
addr string,
cache bool,
logger *zap.Logger
) (*Connection, error) {
// ...
}
```
</td><td>
```go
// package db
type Option interface {
// ...
}
func WithCache(c bool) Option {
// ...
}
func WithLogger(log *zap.Logger) Option {
// ...
}
// Open creates a connection.
func Open(
addr string,
opts ...Option,
) (*Connection, error) {
// ...
}
```
</td></tr>
<tr><td>
必须始终提供缓存和记录器参数，即使用户希望使用默认值。
```go
db.Open(addr, db.DefaultCache, zap.NewNop())
db.Open(addr, db.DefaultCache, log)
db.Open(addr, false /* cache */, zap.NewNop())
db.Open(addr, false /* cache */, log)
```
</td><td>
只有在需要时才提供选项。
```go
db.Open(addr)
db.Open(addr, db.WithLogger(log))
db.Open(addr, db.WithCache(false))
db.Open(
addr,
db.WithCache(false),
db.WithLogger(log),
)
```
</td></tr>
</tbody></table>
我们建议实现此模式的方法是使用一个 `Option` 接口，该接口保存一个未导出的方法，在一个未导出的 `options` 结构上记录选项。
```go
type options struct {
cache bool
logger *zap.Logger
}
type Option interface {
apply(*options)
}
type cacheOption bool
func (c cacheOption) apply(opts *options) {
opts.cache = bool(c)
}
func WithCache(c bool) Option {
return cacheOption(c)
}
type loggerOption struct {
Log *zap.Logger
}
func (l loggerOption) apply(opts *options) {
opts.logger = l.Log
}
func WithLogger(log *zap.Logger) Option {
return loggerOption{Log: log}
}
// Open creates a connection.
func Open(
addr string,
opts ...Option,
) (*Connection, error) {
options := options{
cache: defaultCache,
logger: zap.NewNop(),
}
for _, o := range opts {
o.apply(&options)
}
// ...
}
```
注意：还有一种使用闭包实现这个模式的方法，但是我们相信上面的模式为作者提供了更多的灵活性，并且更容易对用户进行调试和测试。特别是，我们的这种方式允许在测试和模拟中比较选项，这在闭包实现中几乎是不可能的。此外，它还允许选项实现其他接口，包括 `fmt.Stringer`，允许用户读取选项的字符串表示形式。
还可以参考下面资料：
- [Self-referential functions and the design of options]
- [Functional options for friendly APIs]
[Self-referential functions and the design of options]: https://commandcenter.blogspot.com/2014/01/self-referential-functions-and-design.html
[Functional options for friendly APIs]: https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis
<!-- TODO: replace this with parameter structs and functional options, when to
use one vs other -->
## Linting
比任何 "blessed" linter 集更重要的是，lint 在一个代码库中始终保持一致。
我们建议至少使用以下 linters，因为我认为它们有助于发现最常见的问题，并在不需要规定的情况下为代码质量建立一个高标准：
- [errcheck] 以确保错误得到处理
- [goimports] 格式化代码和管理 imports
- [golint] 指出常见的文体错误
- [govet] 分析代码中的常见错误
- [staticcheck] 各种静态分析检查
[errcheck]: https://github.com/kisielk/errcheck
[goimports]: https://pkg.go.dev/golang.org/x/tools/cmd/goimports
[golint]: https://github.com/golang/lint
[govet]: https://golang.org/cmd/vet/
[staticcheck]: https://staticcheck.io/
### Lint Runners
我们推荐 [golangci-lint] 作为 go-to lint 的运行程序，这主要是因为它在较大的代码库中的性能以及能够同时配置和使用许多规范。这个 repo 有一个示例配置文件 [.golangci.yml] 和推荐的 linter 设置。
golangci-lint 有 [various-linters] 可供使用。建议将上述 linters 作为基本 set，我们鼓励团队添加对他们的项目有意义的任何附加 linters。
[golangci-lint]: https://github.com/golangci/golangci-lint
[.golangci.yml]: https://github.com/uber-go/guide/blob/master/.golangci.yml
[various-linters]: https://golangci-lint.run/usage/linters/
## Stargazers over time
[](https://starchart.cc/xxjwxc/uber_go_guide_cn)
================================================
FILE: src/README.md
================================================
The contents of this directory are used to generate the top-level style.md.
The layout is controlled by SUMMARY.md.
================================================
FILE: src/SUMMARY.md
================================================
# Uber Go Style Guide
- [Introduction](intro.md)
- Guidelines
- [Pointers to Interfaces](interface-pointer.md)
- [Verify Interface Compliance](interface-compliance.md)
- [Receivers and Interfaces](interface-receiver.md)
- [Zero-value Mutexes are Valid](mutex-zero-value.md)
- [Copy Slices and Maps at Boundaries](container-copy.md)
- [Defer to Clean Up](defer-clean.md)
- [Channel Size is One or None](channel-size.md)
- [Start Enums at One](enum-start.md)
- [Use `"time"` to handle time](time.md)
- Errors
- [Error Types](error-type.md)
- [Error Wrapping](error-wrap.md)
- [Error Naming](error-name.md)
- [Handle Errors Once](error-once.md)
- [Handle Type Assertion Failures](type-assert.md)
- [Don't Panic](panic.md)
- [Use go.uber.org/atomic](atomic.md)
- [Avoid Mutable Globals](global-mut.md)
- [Avoid Embedding Types in Public Structs](embed-public.md)
- [Avoid Using Built-In Names](builtin-name.md)
- [Avoid `init()`](init.md)
- [Exit in Main](exit-main.md)
- [Exit Once](exit-once.md)
- [Use field tags in marshaled structs](struct-tag.md)
- [Don't fire-and-forget goroutines](goroutine-forget.md)
- [Wait for goroutines to exit](goroutine-exit.md)
- [No goroutines in `init()`](goroutine-init.md)
- [Performance](performance.md)
- [Prefer strconv over fmt](strconv.md)
- [Avoid repeated string-to-byte conversions](string-byte-slice.md)
- [Prefer Specifying Container Capacity](container-capacity.md)
- Style
- [Avoid overly long lines](line-length.md)
- [Be Consistent](consistency.md)
- [Group Similar Declarations](decl-group.md)
- [Import Group Ordering](import-group.md)
- [Package Names](package-name.md)
- [Function Names](function-name.md)
- [Import Aliasing](import-alias.md)
- [Function Grouping and Ordering](function-order.md)
- [Reduce Nesting](nest-less.md)
- [Unnecessary Else](else-unnecessary.md)
- [Top-level Variable Declarations](global-decl.md)
- [Prefix Unexported Globals with _](global-name.md)
- [Embedding in Structs](struct-embed.md)
- [Local Variable Declarations](var-decl.md)
- [nil is a valid slice](slice-nil.md)
- [Reduce Scope of Variables](var-scope.md)
- [Avoid Naked Parameters](param-naked.md)
- [Use Raw String Literals to Avoid Escaping](string-escape.md)
- Initializing Structs
- [Use Field Names to Initialize Structs](struct-field-key.md)
- [Omit Zero Value Fields in Structs](struct-field-zero.md)
- [Use `var` for Zero Value Structs](struct-zero.md)
- [Initializing Struct References](struct-pointer.md)
- [Initializing Maps](map-init.md)
- [Format Strings outside Printf](printf-const.md)
- [Naming Printf-style Functions](printf-name.md)
- Patterns
- [Test Tables](test-table.md)
- [Functional Options](functional-option.md)
- [Linting](lint.md)
================================================
FILE: src/atomic.md
================================================
# Use go.uber.org/atomic
Atomic operations with the [sync/atomic] package operate on the raw types
(`int32`, `int64`, etc.) so it is easy to forget to use the atomic operation to
read or modify the variables.
[go.uber.org/atomic] adds type safety to these operations by hiding the
underlying type. Additionally, it includes a convenient `atomic.Bool` type.
[go.uber.org/atomic]: https://pkg.go.dev/go.uber.org/atomic
[sync/atomic]: https://pkg.go.dev/sync/atomic
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
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!
}
```
</td><td>
```go
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()
}
```
</td></tr>
</tbody></table>
================================================
FILE: src/builtin-name.md
================================================
# Avoid Using Built-In Names
The Go [language specification] outlines several built-in,
[predeclared identifiers] that should not be used as names within Go programs.
Depending on context, reusing these identifiers as names will either shadow
the original within the current lexical scope (and any nested scopes) or make
affected code confusing. In the best case, the compiler will complain; in the
worst case, such code may introduce latent, hard-to-grep bugs.
[language specification]: https://go.dev/ref/spec
[predeclared identifiers]: https://go.dev/ref/spec#Predeclared_identifiers
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
var error string
// `error` shadows the builtin
// or
func handleErrorMessage(error string) {
// `error` shadows the builtin
}
```
</td><td>
```go
var errorMessage string
// `error` refers to the builtin
// or
func handleErrorMessage(msg string) {
// `error` refers to the builtin
}
```
</td></tr>
<tr><td>
```go
type Foo struct {
// While these fields technically don't
// constitute shadowing, grepping for
// `error` or `string` strings is now
// ambiguous.
error error
string string
}
func (f Foo) Error() error {
// `error` and `f.error` are
// visually similar
return f.error
}
func (f Foo) String() string {
// `string` and `f.string` are
// visually similar
return f.string
}
```
</td><td>
```go
type Foo struct {
// `error` and `string` strings are
// now unambiguous.
err error
str string
}
func (f Foo) Error() error {
return f.err
}
func (f Foo) String() string {
return f.str
}
```
</td></tr>
</tbody></table>
Note that the compiler will not generate errors when using predeclared
identifiers, but tools such as `go vet` should correctly point out these and
other cases of shadowing.
================================================
FILE: src/channel-size.md
================================================
# Channel Size is One or None
Channels should usually have a size of one or be unbuffered. By default,
channels are unbuffered and have a size of zero. Any other size
must be subject to a high level of scrutiny. Consider how the size is
determined, what prevents the channel from filling up under load and blocking
writers, and what happens when this occurs.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// Ought to be enough for anybody!
c := make(chan int, 64)
```
</td><td>
```go
// Size of one
c := make(chan int, 1) // or
// Unbuffered channel, size of zero
c := make(chan int)
```
</td></tr>
</tbody></table>
================================================
FILE: src/consistency.md
================================================
# Be Consistent
Some of the guidelines outlined in this document can be evaluated objectively;
others are situational, contextual, or subjective.
Above all else, **be consistent**.
Consistent code is easier to maintain, is easier to rationalize, requires less
cognitive overhead, and is easier to migrate or update as new conventions emerge
or classes of bugs are fixed.
Conversely, having multiple disparate or conflicting styles within a single
codebase causes maintenance overhead, uncertainty, and cognitive dissonance,
all of which can directly contribute to lower velocity, painful code reviews,
and bugs.
When applying these guidelines to a codebase, it is recommended that changes
are made at a package (or larger) level: application at a sub-package level
violates the above concern by introducing multiple styles into the same code.
================================================
FILE: src/container-capacity.md
================================================
# Prefer Specifying Container Capacity
Specify container capacity where possible in order to allocate memory for the
container up front. This minimizes subsequent allocations (by copying and
resizing of the container) as elements are added.
## Specifying Map Capacity Hints
Where possible, provide capacity hints when initializing
maps with `make()`.
```go
make(map[T1]T2, hint)
```
Providing a capacity hint to `make()` tries to right-size the
map at initialization time, which reduces the need for growing
the map and allocations as elements are added to the map.
Note that, unlike slices, map capacity hints do not guarantee complete,
preemptive allocation, but are used to approximate the number of hashmap buckets
required. Consequently, allocations may still occur when adding elements to the
map, even up to the specified capacity.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
m := make(map[string]os.FileInfo)
files, _ := os.ReadDir("./files")
for _, f := range files {
m[f.Name()] = f
}
```
</td><td>
```go
files, _ := os.ReadDir("./files")
m := make(map[string]os.DirEntry, len(files))
for _, f := range files {
m[f.Name()] = f
}
```
</td></tr>
<tr><td>
`m` is created without a size hint; there may be more
allocations at assignment time.
</td><td>
`m` is created with a size hint; there may be fewer
allocations at assignment time.
</td></tr>
</tbody></table>
## Specifying Slice Capacity
Where possible, provide capacity hints when initializing slices with `make()`,
particularly when appending.
```go
make([]T, length, capacity)
```
Unlike maps, slice capacity is not a hint: the compiler will allocate enough
memory for the capacity of the slice as provided to `make()`, which means that
subsequent `append()` operations will incur zero allocations (until the length
of the slice matches the capacity, after which any appends will require a resize
to hold additional elements).
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
for n := 0; n < b.N; n++ {
data := make([]int, 0)
for k := 0; k < size; k++{
data = append(data, k)
}
}
```
</td><td>
```go
for n := 0; n < b.N; n++ {
data := make([]int, 0, size)
for k := 0; k < size; k++{
data = append(data, k)
}
}
```
</td></tr>
<tr><td>
```plain
BenchmarkBad-4 100000000 2.48s
```
</td><td>
```plain
BenchmarkGood-4 100000000 0.21s
```
</td></tr>
</tbody></table>
================================================
FILE: src/container-copy.md
================================================
# Copy Slices and Maps at Boundaries
Slices and maps contain pointers to the underlying data so be wary of scenarios
when they need to be copied.
## Receiving Slices and Maps
Keep in mind that users can modify a map or slice you received as an argument
if you store a reference to it.
<table>
<thead><tr><th>Bad</th> <th>Good</th></tr></thead>
<tbody>
<tr>
<td>
```go
func (d *Driver) SetTrips(trips []Trip) {
d.trips = trips
}
trips := ...
d1.SetTrips(trips)
// Did you mean to modify d1.trips?
trips[0] = ...
```
</td>
<td>
```go
func (d *Driver) SetTrips(trips []Trip) {
d.trips = make([]Trip, len(trips))
copy(d.trips, trips)
}
trips := ...
d1.SetTrips(trips)
// We can now modify trips[0] without affecting d1.trips.
trips[0] = ...
```
</td>
</tr>
</tbody>
</table>
## Returning Slices and Maps
Similarly, be wary of user modifications to maps or slices exposing internal
state.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Stats struct {
mu sync.Mutex
counters map[string]int
}
// Snapshot returns the current stats.
func (s *Stats) Snapshot() map[string]int {
s.mu.Lock()
defer s.mu.Unlock()
return s.counters
}
// snapshot is no longer protected by the mutex, so any
// access to the snapshot is subject to data races.
snapshot := stats.Snapshot()
```
</td><td>
```go
type Stats struct {
mu sync.Mutex
counters map[string]int
}
func (s *Stats) Snapshot() map[string]int {
s.mu.Lock()
defer s.mu.Unlock()
result := make(map[string]int, len(s.counters))
for k, v := range s.counters {
result[k] = v
}
return result
}
// Snapshot is now a copy.
snapshot := stats.Snapshot()
```
</td></tr>
</tbody></table>
================================================
FILE: src/decl-group.md
================================================
# Group Similar Declarations
Go supports grouping similar declarations.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
import "a"
import "b"
```
</td><td>
```go
import (
"a"
"b"
)
```
</td></tr>
</tbody></table>
This also applies to constants, variables, and type declarations.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
const a = 1
const b = 2
var a = 1
var b = 2
type Area float64
type Volume float64
```
</td><td>
```go
const (
a = 1
b = 2
)
var (
a = 1
b = 2
)
type (
Area float64
Volume float64
)
```
</td></tr>
</tbody></table>
Only group related declarations. Do not group declarations that are unrelated.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Operation int
const (
Add Operation = iota + 1
Subtract
Multiply
EnvVar = "MY_ENV"
)
```
</td><td>
```go
type Operation int
const (
Add Operation = iota + 1
Subtract
Multiply
)
const EnvVar = "MY_ENV"
```
</td></tr>
</tbody></table>
Groups are not limited in where they can be used. For example, you can use them
inside of functions.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func f() string {
red := color.New(0xff0000)
green := color.New(0x00ff00)
blue := color.New(0x0000ff)
// ...
}
```
</td><td>
```go
func f() string {
var (
red = color.New(0xff0000)
green = color.New(0x00ff00)
blue = color.New(0x0000ff)
)
// ...
}
```
</td></tr>
</tbody></table>
Exception: Variable declarations, particularly inside functions, should be
grouped together if declared adjacent to other variables. Do this for variables
declared together even if they are unrelated.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func (c *client) request() {
caller := c.name
format := "json"
timeout := 5*time.Second
var err error
// ...
}
```
</td><td>
```go
func (c *client) request() {
var (
caller = c.name
format = "json"
timeout = 5*time.Second
err error
)
// ...
}
```
</td></tr>
</tbody></table>
================================================
FILE: src/defer-clean.md
================================================
# Defer to Clean Up
Use defer to clean up resources such as files and locks.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
p.Lock()
if p.count < 10 {
p.Unlock()
return p.count
}
p.count++
newCount := p.count
p.Unlock()
return newCount
// easy to miss unlocks due to multiple returns
```
</td><td>
```go
p.Lock()
defer p.Unlock()
if p.count < 10 {
return p.count
}
p.count++
return p.count
// more readable
```
</td></tr>
</tbody></table>
Defer has an extremely small overhead and should be avoided only if you can
prove that your function execution time is in the order of nanoseconds. The
readability win of using defers is worth the miniscule cost of using them. This
is especially true for larger methods that have more than simple memory
accesses, where the other computations are more significant than the `defer`.
================================================
FILE: src/else-unnecessary.md
================================================
# Unnecessary Else
If a variable is set in both branches of an if, it can be replaced with a
single if.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
var a int
if b {
a = 100
} else {
a = 10
}
```
</td><td>
```go
a := 10
if b {
a = 100
}
```
</td></tr>
</tbody></table>
================================================
FILE: src/embed-public.md
================================================
# Avoid Embedding Types in Public Structs
These embedded types leak implementation details, inhibit type evolution, and
obscure documentation.
Assuming you have implemented a variety of list types using a shared
`AbstractList`, avoid embedding the `AbstractList` in your concrete list
implementations.
Instead, hand-write only the methods to your concrete list that will delegate
to the abstract list.
```go
type AbstractList struct {}
// Add adds an entity to the list.
func (l *AbstractList) Add(e Entity) {
// ...
}
// Remove removes an entity from the list.
func (l *AbstractList) Remove(e Entity) {
// ...
}
```
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// ConcreteList is a list of entities.
type ConcreteList struct {
*AbstractList
}
```
</td><td>
```go
// ConcreteList is a list of entities.
type ConcreteList struct {
list *AbstractList
}
// Add adds an entity to the list.
func (l *ConcreteList) Add(e Entity) {
l.list.Add(e)
}
// Remove removes an entity from the list.
func (l *ConcreteList) Remove(e Entity) {
l.list.Remove(e)
}
```
</td></tr>
</tbody></table>
Go allows [type embedding] as a compromise between inheritance and composition.
The outer type gets implicit copies of the embedded type's methods.
These methods, by default, delegate to the same method of the embedded
instance.
[type embedding]: https://go.dev/doc/effective_go#embedding
The struct also gains a field by the same name as the type.
So, if the embedded type is public, the field is public.
To maintain backward compatibility, every future version of the outer type must
keep the embedded type.
An embedded type is rarely necessary.
It is a convenience that helps you avoid writing tedious delegate methods.
Even embedding a compatible AbstractList *interface*, instead of the struct,
would offer the developer more flexibility to change in the future, but still
leak the detail that the concrete lists use an abstract implementation.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// AbstractList is a generalized implementation
// for various kinds of lists of entities.
type AbstractList interface {
Add(Entity)
Remove(Entity)
}
// ConcreteList is a list of entities.
type ConcreteList struct {
AbstractList
}
```
</td><td>
```go
// ConcreteList is a list of entities.
type ConcreteList struct {
list AbstractList
}
// Add adds an entity to the list.
func (l *ConcreteList) Add(e Entity) {
l.list.Add(e)
}
// Remove removes an entity from the list.
func (l *ConcreteList) Remove(e Entity) {
l.list.Remove(e)
}
```
</td></tr>
</tbody></table>
Either with an embedded struct or an embedded interface, the embedded type
places limits on the evolution of the type.
- Adding methods to an embedded interface is a breaking change.
- Removing methods from an embedded struct is a breaking change.
- Removing the embedded type is a breaking change.
- Replacing the embedded type, even with an alternative that satisfies the same
interface, is a breaking change.
Although writing these delegate methods is tedious, the additional effort hides
an implementation detail, leaves more opportunities for change, and also
eliminates indirection for discovering the full List interface in
documentation.
================================================
FILE: src/enum-start.md
================================================
# Start Enums at One
The standard way of introducing enumerations in Go is to declare a custom type
and a `const` group with `iota`. Since variables have a 0 default value, you
should usually start your enums on a non-zero value.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Operation int
const (
Add Operation = iota
Subtract
Multiply
)
// Add=0, Subtract=1, Multiply=2
```
</td><td>
```go
type Operation int
const (
Add Operation = iota + 1
Subtract
Multiply
)
// Add=1, Subtract=2, Multiply=3
```
</td></tr>
</tbody></table>
There are cases where using the zero value makes sense, for example when the
zero value case is the desirable default behavior.
```go
type LogOutput int
const (
LogToStdout LogOutput = iota
LogToFile
LogToRemote
)
// LogToStdout=0, LogToFile=1, LogToRemote=2
```
<!-- TODO: section on String methods for enums -->
================================================
FILE: src/error-name.md
================================================
# Error Naming
For error values stored as global variables,
use the prefix `Err` or `err` depending on whether they're exported.
This guidance supersedes the [Prefix Unexported Globals with _](global-name.md).
```go
var (
// The following two errors are exported
// so that users of this package can match them
// with errors.Is.
ErrBrokenLink = errors.New("link is broken")
ErrCouldNotOpen = errors.New("could not open")
// This error is not exported because
// we don't want to make it part of our public API.
// We may still use it inside the package
// with errors.Is.
errNotFound = errors.New("not found")
)
```
For custom error types, use the suffix `Error` instead.
```go
// Similarly, this error is exported
// so that users of this package can match it
// with errors.As.
type NotFoundError struct {
File string
}
func (e *NotFoundError) Error() string {
return fmt.Sprintf("file %q not found", e.File)
}
// And this error is not exported because
// we don't want to make it part of the public API.
// We can still use it inside the package
// with errors.As.
type resolveError struct {
Path string
}
func (e *resolveError) Error() string {
return fmt.Sprintf("resolve %q", e.Path)
}
```
================================================
FILE: src/error-once.md
================================================
# Handle Errors Once
When a caller receives an error from a callee,
it can handle it in a variety of different ways
depending on what it knows about the error.
These include, but not are limited to:
- if the callee contract defines specific errors,
matching the error with `errors.Is` or `errors.As`
and handling the branches differently
- if the error is recoverable,
logging the error and degrading gracefully
- if the error represents a domain-specific failure condition,
returning a well-defined error
- returning the error, either [wrapped](error-wrap.md) or verbatim
Regardless of how the caller handles the error,
it should typically handle each error only once.
The caller should not, for example, log the error and then return it,
because *its* callers may handle the error as well.
For example, consider the following cases:
<table>
<thead><tr><th>Description</th><th>Code</th></tr></thead>
<tbody>
<tr><td>
**Bad**: Log the error and return it
Callers further up the stack will likely take a similar action with the error.
Doing so causing a lot of noise in the application logs for little value.
</td><td>
```go
u, err := getUser(id)
if err != nil {
// BAD: See description
log.Printf("Could not get user %q: %v", id, err)
return err
}
```
</td></tr>
<tr><td>
**Good**: Wrap the error and return it
Callers further up the stack will handle the error.
Use of `%w` ensures they can match the error with `errors.Is` or `errors.As`
if relevant.
</td><td>
```go
u, err := getUser(id)
if err != nil {
return fmt.Errorf("get user %q: %w", id, err)
}
```
</td></tr>
<tr><td>
**Good**: Log the error and degrade gracefully
If the operation isn't strictly necessary,
we can provide a degraded but unbroken experience
by recovering from it.
</td><td>
```go
if err := emitMetrics(); err != nil {
// Failure to write metrics should not
// break the application.
log.Printf("Could not emit metrics: %v", err)
}
```
</td></tr>
<tr><td>
**Good**: Match the error and degrade gracefully
If the callee defines a specific error in its contract,
and the failure is recoverable,
match on that error case and degrade gracefully.
For all other cases, wrap the error and return it.
Callers further up the stack will handle other errors.
</td><td>
```go
tz, err := getUserTimeZone(id)
if err != nil {
if errors.Is(err, ErrUserNotFound) {
// User doesn't exist. Use UTC.
tz = time.UTC
} else {
return fmt.Errorf("get user %q: %w", id, err)
}
}
```
</td></tr>
</tbody></table>
================================================
FILE: src/error-type.md
================================================
# Error Types
There are few options for declaring errors.
Consider the following before picking the option best suited for your use case.
- Does the caller need to match the error so that they can handle it?
If yes, we must support the [`errors.Is`] or [`errors.As`] functions
by declaring a top-level error variable or a custom type.
- Is the error message a static string,
or is it a dynamic string that requires contextual information?
For the former, we can use [`errors.New`], but for the latter we must
use [`fmt.Errorf`] or a custom error type.
- Are we propagating a new error returned by a downstream function?
If so, see the [section on error wrapping](error-wrap.md).
[`errors.Is`]: https://pkg.go.dev/errors#Is
[`errors.As`]: https://pkg.go.dev/errors#As
| Error matching? | Error Message | Guidance |
|-----------------|---------------|-------------------------------------|
| No | static | [`errors.New`] |
| No | dynamic | [`fmt.Errorf`] |
| Yes | static | top-level `var` with [`errors.New`] |
| Yes | dynamic | custom `error` type |
[`errors.New`]: https://pkg.go.dev/errors#New
[`fmt.Errorf`]: https://pkg.go.dev/fmt#Errorf
For example,
use [`errors.New`] for an error with a static string.
Export this error as a variable to support matching it with `errors.Is`
if the caller needs to match and handle this error.
<table>
<thead><tr><th>No error matching</th><th>Error matching</th></tr></thead>
<tbody>
<tr><td>
```go
// package foo
func Open() error {
return errors.New("could not open")
}
// package bar
if err := foo.Open(); err != nil {
// Can't handle the error.
panic("unknown error")
}
```
</td><td>
```go
// package foo
var ErrCouldNotOpen = errors.New("could not open")
func Open() error {
return ErrCouldNotOpen
}
// package bar
if err := foo.Open(); err != nil {
if errors.Is(err, foo.ErrCouldNotOpen) {
// handle the error
} else {
panic("unknown error")
}
}
```
</td></tr>
</tbody></table>
For an error with a dynamic string,
use [`fmt.Errorf`] if the caller does not need to match it,
and a custom `error` if the caller does need to match it.
<table>
<thead><tr><th>No error matching</th><th>Error matching</th></tr></thead>
<tbody>
<tr><td>
```go
// package foo
func Open(file string) error {
return fmt.Errorf("file %q not found", file)
}
// package bar
if err := foo.Open("testfile.txt"); err != nil {
// Can't handle the error.
panic("unknown error")
}
```
</td><td>
```go
// package foo
type NotFoundError struct {
File string
}
func (e *NotFoundError) Error() string {
return fmt.Sprintf("file %q not found", e.File)
}
func Open(file string) error {
return &NotFoundError{File: file}
}
// package bar
if err := foo.Open("testfile.txt"); err != nil {
var notFound *NotFoundError
if errors.As(err, ¬Found) {
// handle the error
} else {
panic("unknown error")
}
}
```
</td></tr>
</tbody></table>
Note that if you export error variables or types from a package,
they will become part of the public API of the package.
================================================
FILE: src/error-wrap.md
================================================
# Error Wrapping
There are three main options for propagating errors if a call fails:
- return the original error as-is
- add context with `fmt.Errorf` and the `%w` verb
- add context with `fmt.Errorf` and the `%v` verb
Return the original error as-is if there is no additional context to add.
This maintains the original error type and message.
This is well suited for cases when the underlying error message
has sufficient information to track down where it came from.
Otherwise, add context to the error message where possible
so that instead of a vague error such as "connection refused",
you get more useful errors such as "call service foo: connection refused".
Use `fmt.Errorf` to add context to your errors,
picking between the `%w` or `%v` verbs
based on whether the caller should be able to
match and extract the underlying cause.
- Use `%w` if the caller should have access to the underlying error.
This is a good default for most wrapped errors,
but be aware that callers may begin to rely on this behavior.
So for cases where the wrapped error is a known `var` or type,
document and test it as part of your function's contract.
- Use `%v` to obfuscate the underlying error.
Callers will be unable to match it,
but you can switch to `%w` in the future if needed.
When adding context to returned errors, keep the context succinct by avoiding
phrases like "failed to", which state the obvious and pile up as the error
percolates up through the stack:
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
s, err := store.New()
if err != nil {
return fmt.Errorf(
"failed to create new store: %w", err)
}
```
</td><td>
```go
s, err := store.New()
if err != nil {
return fmt.Errorf(
"new store: %w", err)
}
```
</td></tr><tr><td>
```plain
failed to x: failed to y: failed to create new store: the error
```
</td><td>
```plain
x: y: new store: the error
```
</td></tr>
</tbody></table>
However once the error is sent to another system, it should be clear the
message is an error (e.g. an `err` tag or "Failed" prefix in logs).
See also [Don't just check errors, handle them gracefully].
[Don't just check errors, handle them gracefully]: https://dave.cheney.net/2016/04/27/dont-just-check-errors-handle-them-gracefully
================================================
FILE: src/exit-main.md
================================================
# Exit in Main
Go programs use [`os.Exit`] or [`log.Fatal*`] to exit immediately. (Panicking
is not a good way to exit programs, please [don't panic](panic.md).)
[`os.Exit`]: https://pkg.go.dev/os#Exit
[`log.Fatal*`]: https://pkg.go.dev/log#Fatal
Call one of `os.Exit` or `log.Fatal*` **only in `main()`**. All other
functions should return errors to signal failure.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func main() {
body := readFile(path)
fmt.Println(body)
}
func readFile(path string) string {
f, err := os.Open(path)
if err != nil {
log.Fatal(err)
}
b, err := io.ReadAll(f)
if err != nil {
log.Fatal(err)
}
return string(b)
}
```
</td><td>
```go
func main() {
body, err := readFile(path)
if err != nil {
log.Fatal(err)
}
fmt.Println(body)
}
func readFile(path string) (string, error) {
f, err := os.Open(path)
if err != nil {
return "", err
}
b, err := io.ReadAll(f)
if err != nil {
return "", err
}
return string(b), nil
}
```
</td></tr>
</tbody></table>
Rationale: Programs with multiple functions that exit present a few issues:
- Non-obvious control flow: Any function can exit the program so it becomes
difficult to reason about the control flow.
- Difficult to test: A function that exits the program will also exit the test
calling it. This makes the function difficult to test and introduces risk of
skipping other tests that have not yet been run by `go test`.
- Skipped cleanup: When a function exits the program, it skips function calls
enqueued with `defer` statements. This adds risk of skipping important
cleanup tasks.
================================================
FILE: src/exit-once.md
================================================
# Exit Once
If possible, prefer to call `os.Exit` or `log.Fatal` **at most once** in your
`main()`. If there are multiple error scenarios that halt program execution,
put that logic under a separate function and return errors from it.
This has the effect of shortening your `main()` function and putting all key
business logic into a separate, testable function.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
package main
func main() {
args := os.Args[1:]
if len(args) != 1 {
log.Fatal("missing file")
}
name := args[0]
f, err := os.Open(name)
if err != nil {
log.Fatal(err)
}
defer f.Close()
// If we call log.Fatal after this line,
// f.Close will not be called.
b, err := io.ReadAll(f)
if err != nil {
log.Fatal(err)
}
// ...
}
```
</td><td>
```go
package main
func main() {
if err := run(); err != nil {
log.Fatal(err)
}
}
func run() error {
args := os.Args[1:]
if len(args) != 1 {
return errors.New("missing file")
}
name := args[0]
f, err := os.Open(name)
if err != nil {
return err
}
defer f.Close()
b, err := io.ReadAll(f)
if err != nil {
return err
}
// ...
}
```
</td></tr>
</tbody></table>
The example above uses `log.Fatal`, but the guidance also applies to
`os.Exit` or any library code that calls `os.Exit`.
```go
func main() {
if err := run(); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
```
You may alter the signature of `run()` to fit your needs.
For example, if your program must exit with specific exit codes for failures,
`run()` may return the exit code instead of an error.
This allows unit tests to verify this behavior directly as well.
```go
func main() {
os.Exit(run(args))
}
func run() (exitCode int) {
// ...
}
```
More generally, note that the `run()` function used in these examples
is not intended to be prescriptive.
There's flexibility in the name, signature, and setup of the `run()` function.
Among other things, you may:
- accept unparsed command line arguments (e.g., `run(os.Args[1:])`)
- parse command line arguments in `main()` and pass them onto `run`
- use a custom error type to carry the exit code back to `main()`
- put business logic in a different layer of abstraction from `package main`
This guidance only requires that there's a single place in your `main()`
responsible for actually exiting the process.
================================================
FILE: src/function-name.md
================================================
# Function Names
We follow the Go community's convention of using [MixedCaps for function
names]. An exception is made for test functions, which may contain underscores
for the purpose of grouping related test cases, e.g.,
`TestMyFunction_WhatIsBeingTested`.
[MixedCaps for function names]: https://go.dev/doc/effective_go#mixed-caps
================================================
FILE: src/function-order.md
================================================
# Function Grouping and Ordering
- Functions should be sorted in rough call order.
- Functions in a file should be grouped by receiver.
Therefore, exported functions should appear first in a file, after
`struct`, `const`, `var` definitions.
A `newXYZ()`/`NewXYZ()` may appear after the type is defined, but before the
rest of the methods on the receiver.
Since functions are grouped by receiver, plain utility functions should appear
towards the end of the file.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
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{}
}
```
</td><td>
```go
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 {...}
```
</td></tr>
</tbody></table>
================================================
FILE: src/functional-option.md
================================================
# Functional Options
Functional options is a pattern in which you declare an opaque `Option` type
that records information in some internal struct. You accept a variadic number
of these options and act upon the full information recorded by the options on
the internal struct.
Use this pattern for optional arguments in constructors and other public APIs
that you foresee needing to expand, especially if you already have three or
more arguments on those functions.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// package db
func Open(
addr string,
cache bool,
logger *zap.Logger
) (*Connection, error) {
// ...
}
```
</td><td>
```go
// package db
type Option interface {
// ...
}
func WithCache(c bool) Option {
// ...
}
func WithLogger(log *zap.Logger) Option {
// ...
}
// Open creates a connection.
func Open(
addr string,
opts ...Option,
) (*Connection, error) {
// ...
}
```
</td></tr>
<tr><td>
The cache and logger parameters must always be provided, even if the user
wants to use the default.
```go
db.Open(addr, db.DefaultCache, zap.NewNop())
db.Open(addr, db.DefaultCache, log)
db.Open(addr, false /* cache */, zap.NewNop())
db.Open(addr, false /* cache */, log)
```
</td><td>
Options are provided only if needed.
```go
db.Open(addr)
db.Open(addr, db.WithLogger(log))
db.Open(addr, db.WithCache(false))
db.Open(
addr,
db.WithCache(false),
db.WithLogger(log),
)
```
</td></tr>
</tbody></table>
Our suggested way of implementing this pattern is with an `Option` interface
that holds an unexported method, recording options on an unexported `options`
struct.
```go
type options struct {
cache bool
logger *zap.Logger
}
type Option interface {
apply(*options)
}
type cacheOption bool
func (c cacheOption) apply(opts *options) {
opts.cache = bool(c)
}
func WithCache(c bool) Option {
return cacheOption(c)
}
type loggerOption struct {
Log *zap.Logger
}
func (l loggerOption) apply(opts *options) {
opts.logger = l.Log
}
func WithLogger(log *zap.Logger) Option {
return loggerOption{Log: log}
}
// Open creates a connection.
func Open(
addr string,
opts ...Option,
) (*Connection, error) {
options := options{
cache: defaultCache,
logger: zap.NewNop(),
}
for _, o := range opts {
o.apply(&options)
}
// ...
}
```
Note that there's a method of implementing this pattern with closures but we
believe that the pattern above provides more flexibility for authors and is
easier to debug and test for users. In particular, it allows options to be
compared against each other in tests and mocks, versus closures where this is
impossible. Further, it lets options implement other interfaces, including
`fmt.Stringer` which allows for user-readable string representations of the
options.
See also,
- [Self-referential functions and the design of options]
- [Functional options for friendly APIs]
[Self-referential functions and the design of options]: https://commandcenter.blogspot.com/2014/01/self-referential-functions-and-design.html
[Functional options for friendly APIs]: https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis
<!-- TODO: replace this with parameter structs and functional options, when to
use one vs other -->
================================================
FILE: src/global-decl.md
================================================
# Top-level Variable Declarations
At the top level, use the standard `var` keyword. Do not specify the type,
unless it is not the same type as the expression.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
var _s string = F()
func F() string { return "A" }
```
</td><td>
```go
var _s = F()
// Since F already states that it returns a string, we don't need to specify
// the type again.
func F() string { return "A" }
```
</td></tr>
</tbody></table>
Specify the type if the type of the expression does not match the desired type
exactly.
```go
type myError struct{}
func (myError) Error() string { return "error" }
func F() myError { return myError{} }
var _e error = F()
// F returns an object of type myError but we want error.
```
================================================
FILE: src/global-mut.md
================================================
# Avoid Mutable Globals
Avoid mutating global variables, instead opting for dependency injection.
This applies to function pointers as well as other kinds of values.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// sign.go
var _timeNow = time.Now
func sign(msg string) string {
now := _timeNow()
return signWithTime(msg, now)
}
```
</td><td>
```go
// sign.go
type signer struct {
now func() time.Time
}
func newSigner() *signer {
return &signer{
now: time.Now,
}
}
func (s *signer) Sign(msg string) string {
now := s.now()
return signWithTime(msg, now)
}
```
</td></tr>
<tr><td>
```go
// sign_test.go
func TestSign(t *testing.T) {
oldTimeNow := _timeNow
_timeNow = func() time.Time {
return someFixedTime
}
defer func() { _timeNow = oldTimeNow }()
assert.Equal(t, want, sign(give))
}
```
</td><td>
```go
// sign_test.go
func TestSigner(t *testing.T) {
s := newSigner()
s.now = func() time.Time {
return someFixedTime
}
assert.Equal(t, want, s.Sign(give))
}
```
</td></tr>
</tbody></table>
================================================
FILE: src/global-name.md
================================================
# Prefix Unexported Globals with _
Prefix unexported top-level `var`s and `const`s with `_` to make it clear when
they are used that they are global symbols.
Rationale: Top-level variables and constants have a package scope. Using a
generic name makes it easy to accidentally use the wrong value in a different
file.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// 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.
}
```
</td><td>
```go
// foo.go
const (
_defaultPort = 8080
_defaultUser = "user"
)
```
</td></tr>
</tbody></table>
**Exception**: Unexported error values may use the prefix `err` without the underscore.
See [Error Naming](error-name.md).
================================================
FILE: src/goroutine-exit.md
================================================
# Wait for goroutines to exit
Given a goroutine spawned by the system,
there must be a way to wait for the goroutine to exit.
There are two popular ways to do this:
- Use a `sync.WaitGroup`.
Do this if there are multiple goroutines that you want to wait for
```go
var wg sync.WaitGroup
for i := 0; i < N; i++ {
wg.Add(1)
go func() {
defer wg.Done()
// ...
}()
}
// To wait for all to finish:
wg.Wait()
```
- Add another `chan struct{}` that the goroutine closes when it's done.
Do this if there's only one goroutine.
```go
done := make(chan struct{})
go func() {
defer close(done)
// ...
}()
// To wait for the goroutine to finish:
<-done
```
================================================
FILE: src/goroutine-forget.md
================================================
# Don't fire-and-forget goroutines
Goroutines are lightweight, but they're not free:
at minimum, they cost memory for their stack and CPU to be scheduled.
While these costs are small for typical uses of goroutines,
they can cause significant performance issues
when spawned in large numbers without controlled lifetimes.
Goroutines with unmanaged lifetimes can also cause other issues
like preventing unused objects from being garbage collected
and holding onto resources that are otherwise no longer used.
Therefore, do not leak goroutines in production code.
Use [go.uber.org/goleak](https://pkg.go.dev/go.uber.org/goleak)
to test for goroutine leaks inside packages that may spawn goroutines.
In general, every goroutine:
- must have a predictable time at which it will stop running; or
- there must be a way to signal to the goroutine that it should stop
In both cases, there must be a way code to block and wait for the goroutine to
finish.
For example:
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
go func() {
for {
flush()
time.Sleep(delay)
}
}()
```
</td><td>
```go
var (
stop = make(chan struct{}) // tells the goroutine to stop
done = make(chan struct{}) // tells us that the goroutine exited
)
go func() {
defer close(done)
ticker := time.NewTicker(delay)
defer ticker.Stop()
for {
select {
case <-ticker.C:
flush()
case <-stop:
return
}
}
}()
// Elsewhere...
close(stop) // signal the goroutine to stop
<-done // and wait for it to exit
```
</td></tr>
<tr><td>
There's no way to stop this goroutine.
This will run until the application exits.
</td><td>
This goroutine can be stopped with `close(stop)`,
and we can wait for it to exit with `<-done`.
</td></tr>
</tbody></table>
================================================
FILE: src/goroutine-init.md
================================================
# No goroutines in `init()`
`init()` functions should not spawn goroutines.
See also [Avoid init()](init.md).
If a package has need of a background goroutine,
it must expose an object that is responsible for managing a goroutine's
lifetime.
The object must provide a method (`Close`, `Stop`, `Shutdown`, etc)
that signals the background goroutine to stop, and waits for it to exit.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func init() {
go doWork()
}
func doWork() {
for {
// ...
}
}
```
</td><td>
```go
type Worker struct{ /* ... */ }
func NewWorker(...) *Worker {
w := &Worker{
stop: make(chan struct{}),
done: make(chan struct{}),
// ...
}
go w.doWork()
}
func (w *Worker) doWork() {
defer close(w.done)
for {
// ...
case <-w.stop:
return
}
}
// Shutdown tells the worker to stop
// and waits until it has finished.
func (w *Worker) Shutdown() {
close(w.stop)
<-w.done
}
```
</td></tr>
<tr><td>
Spawns a background goroutine unconditionally when the user exports this package.
The user has no control over the goroutine or a means of stopping it.
</td><td>
Spawns the worker only if the user requests it.
Provides a means of shutting down the worker so that the user can free up
resources used by the worker.
Note that you should use `WaitGroup`s if the worker manages multiple
goroutines.
See [Wait for goroutines to exit](goroutine-exit.md).
</td></tr>
</tbody></table>
================================================
FILE: src/import-alias.md
================================================
# Import Aliasing
Import aliasing must be used if the package name does not match the last
element of the import path.
```go
import (
"net/http"
client "example.com/client-go"
trace "example.com/trace/v2"
)
```
In all other scenarios, import aliases should be avoided unless there is a
direct conflict between imports.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
import (
"fmt"
"os"
runtimetrace "runtime/trace"
nettrace "golang.net/x/trace"
)
```
</td><td>
```go
import (
"fmt"
"os"
"runtime/trace"
nettrace "golang.net/x/trace"
)
```
</td></tr>
</tbody></table>
================================================
FILE: src/import-group.md
================================================
# Import Group Ordering
There should be two import groups:
- Standard library
- Everything else
This is the grouping applied by goimports by default.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
import (
"fmt"
"os"
"go.uber.org/atomic"
"golang.org/x/sync/errgroup"
)
```
</td><td>
```go
import (
"fmt"
"os"
"go.uber.org/atomic"
"golang.org/x/sync/errgroup"
)
```
</td></tr>
</tbody></table>
================================================
FILE: src/init.md
================================================
# Avoid `init()`
Avoid `init()` where possible. When `init()` is unavoidable or desirable, code
should attempt to:
1. Be completely deterministic, regardless of program environment or invocation.
2. Avoid depending on the ordering or side-effects of other `init()` functions.
While `init()` ordering is well-known, code can change, and thus
relationships between `init()` functions can make code brittle and
error-prone.
3. Avoid accessing or manipulating global or environment state, such as machine
information, environment variables, working directory, program
arguments/inputs, etc.
4. Avoid I/O, including both filesystem, network, and system calls.
Code that cannot satisfy these requirements likely belongs as a helper to be
called as part of `main()` (or elsewhere in a program's lifecycle), or be
written as part of `main()` itself. In particular, libraries that are intended
to be used by other programs should take special care to be completely
deterministic and not perform "init magic".
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Foo struct {
// ...
}
var _defaultFoo Foo
func init() {
_defaultFoo = Foo{
// ...
}
}
```
</td><td>
```go
var _defaultFoo = Foo{
// ...
}
// or, better, for testability:
var _defaultFoo = defaultFoo()
func defaultFoo() Foo {
return Foo{
// ...
}
}
```
</td></tr>
<tr><td>
```go
type Config struct {
// ...
}
var _config Config
func init() {
// Bad: based on current directory
cwd, _ := os.Getwd()
// Bad: I/O
raw, _ := os.ReadFile(
path.Join(cwd, "config", "config.yaml"),
)
yaml.Unmarshal(raw, &_config)
}
```
</td><td>
```go
type Config struct {
// ...
}
func loadConfig() Config {
cwd, err := os.Getwd()
// handle err
raw, err := os.ReadFile(
path.Join(cwd, "config", "config.yaml"),
)
// handle err
var config Config
yaml.Unmarshal(raw, &config)
return config
}
```
</td></tr>
</tbody></table>
Considering the above, some situations in which `init()` may be preferable or
necessary might include:
- Complex expressions that cannot be represented as single assignments.
- Pluggable hooks, such as `database/sql` dialects, encoding type registries, etc.
- Optimizations to [Google Cloud Functions] and other forms of deterministic
precomputation.
[Google Cloud Functions]: https://cloud.google.com/functions/docs/bestpractices/tips#use_global_variables_to_reuse_objects_in_future_invocations
================================================
FILE: src/interface-compliance.md
================================================
# Verify Interface Compliance
Verify interface compliance at compile time where appropriate. This includes:
- Exported types that are required to implement specific interfaces as part of
their API contract
- Exported or unexported types that are part of a collection of types
implementing the same interface
- Other cases where violating an interface would break users
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Handler struct {
// ...
}
func (h *Handler) ServeHTTP(
w http.ResponseWriter,
r *http.Request,
) {
...
}
```
</td><td>
```go
type Handler struct {
// ...
}
var _ http.Handler = (*Handler)(nil)
func (h *Handler) ServeHTTP(
w http.ResponseWriter,
r *http.Request,
) {
// ...
}
```
</td></tr>
</tbody></table>
The statement `var _ http.Handler = (*Handler)(nil)` will fail to compile if
`*Handler` ever stops matching the `http.Handler` interface.
The right hand side of the assignment should be the zero value of the asserted
type. This is `nil` for pointer types (like `*Handler`), slices, and maps, and
an empty struct for struct types.
```go
type LogHandler struct {
h http.Handler
log *zap.Logger
}
var _ http.Handler = LogHandler{}
func (h LogHandler) ServeHTTP(
w http.ResponseWriter,
r *http.Request,
) {
// ...
}
```
================================================
FILE: src/interface-pointer.md
================================================
# Pointers to Interfaces
You almost never need a pointer to an interface. You should be passing
interfaces as values—the underlying data can still be a pointer.
An interface is two fields:
1. A pointer to some type-specific information. You can think of this as
"type."
2. Data pointer. If the data stored is a pointer, it’s stored directly. If
the data stored is a value, then a pointer to the value is stored.
If you want interface methods to modify the underlying data, you must use a
pointer.
================================================
FILE: src/interface-receiver.md
================================================
# Receivers and Interfaces
Methods with value receivers can be called on pointers as well as values.
Methods with pointer receivers can only be called on pointers or [addressable values].
[addressable values]: https://go.dev/ref/spec#Method_values
For example,
```go
type S struct {
data string
}
func (s S) Read() string {
return s.data
}
func (s *S) Write(str string) {
s.data = str
}
// We cannot get pointers to values stored in maps, because they are not
// addressable values.
sVals := map[int]S{1: {"A"}}
// We can call Read on values stored in the map because Read
// has a value receiver, which does not require the value to
// be addressable.
sVals[1].Read()
// We cannot call Write on values stored in the map because Write
// has a pointer receiver, and it's not possible to get a pointer
// to a value stored in a map.
//
// sVals[1].Write("test")
sPtrs := map[int]*S{1: {"A"}}
// You can call both Read and Write if the map stores pointers,
// because pointers are intrinsically addressable.
sPtrs[1].Read()
sPtrs[1].Write("test")
```
Similarly, an interface can be satisfied by a pointer, even if the method has a
value receiver.
```go
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
// The following doesn't compile, since s2Val is a value, and there is no value receiver for f.
// i = s2Val
```
Effective Go has a good write up on [Pointers vs. Values].
[Pointers vs. Values]: https://go.dev/doc/effective_go#pointers_vs_values
================================================
FILE: src/intro.md
================================================
# Introduction
Styles are the conventions that govern our code. The term style is a bit of a
misnomer, since these conventions cover far more than just source file
formatting—gofmt handles that for us.
The goal of this guide is to manage this complexity by describing in detail the
Dos and Don'ts of writing Go code at Uber. These rules exist to keep the code
base manageable while still allowing engineers to use Go language features
productively.
This guide was originally created by [Prashant Varanasi] and [Simon Newton] as
a way to bring some colleagues up to speed with using Go. Over the years it has
been amended based on feedback from others.
[Prashant Varanasi]: https://github.com/prashantv
[Simon Newton]: https://github.com/nomis52
This documents idiomatic conventions in Go code that we follow at Uber. A lot
of these are general guidelines for Go, while others extend upon external
resources:
1. [Effective Go](https://go.dev/doc/effective_go)
2. [Go Common Mistakes](https://go.dev/wiki/CommonMistakes)
3. [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments)
We aim for the code samples to be accurate for the two most recent minor versions
of Go [releases](https://go.dev/doc/devel/release).
All code should be error-free when run through `golint` and `go vet`. We
recommend setting up your editor to:
- Run `goimports` on save
- Run `golint` and `go vet` to check for errors
You can find information in editor support for Go tools here:
<https://go.dev/wiki/IDEsAndTextEditorPlugins>
================================================
FILE: src/line-length.md
================================================
# Avoid overly long lines
Avoid lines of code that require readers to scroll horizontally
or turn their heads too much.
We recommend a soft line length limit of **99 characters**.
Authors should aim to wrap lines before hitting this limit,
but it is not a hard limit.
Code is allowed to exceed this limit.
================================================
FILE: src/lint.md
================================================
# Linting
More importantly than any "blessed" set of linters, lint consistently across a
codebase.
We recommend using the following linters at a minimum, because we feel that they
help to catch the most common issues and also establish a high bar for code
quality without being unnecessarily prescriptive:
- [errcheck] to ensure that errors are handled
- [goimports] to format code and manage imports
- [golint] to point out common style mistakes
- [govet] to analyze code for common mistakes
- [staticcheck] to do various static analysis checks
[errcheck]: https://github.com/kisielk/errcheck
[goimports]: https://pkg.go.dev/golang.org/x/tools/cmd/goimports
[golint]: https://github.com/golang/lint
[govet]: https://pkg.go.dev/cmd/vet
[staticcheck]: https://staticcheck.dev
## Lint Runners
We recommend [golangci-lint] as the go-to lint runner for Go code, largely due
to its performance in larger codebases and ability to configure and use many
canonical linters at once. This repo has an example [.golangci.yml] config file
with recommended linters and settings.
golangci-lint has [various linters] available for use. The above linters are
recommended as a base set, and we encourage teams to add any additional linters
that make sense for their projects.
[golangci-lint]: https://github.com/golangci/golangci-lint
[.golangci.yml]: https://github.com/uber-go/guide/blob/master/.golangci.yml
[various linters]: https://golangci-lint.run/usage/linters/
================================================
FILE: src/map-init.md
================================================
# Initializing Maps
Prefer `make(..)` for empty maps, and maps populated
programmatically. This makes map initialization visually
distinct from declaration, and it makes it easy to add size
hints later if available.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
var (
// m1 is safe to read and write;
// m2 will panic on writes.
m1 = map[T1]T2{}
m2 map[T1]T2
)
```
</td><td>
```go
var (
// m1 is safe to read and write;
// m2 will panic on writes.
m1 = make(map[T1]T2)
m2 map[T1]T2
)
```
</td></tr>
<tr><td>
Declaration and initialization are visually similar.
</td><td>
Declaration and initialization are visually distinct.
</td></tr>
</tbody></table>
Where possible, provide capacity hints when initializing
maps with `make()`. See
[Specifying Map Capacity Hints](container-capacity.md#specifying-map-capacity-hints)
for more information.
On the other hand, if the map holds a fixed list of elements,
use map literals to initialize the map.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
m := make(map[T1]T2, 3)
m[k1] = v1
m[k2] = v2
m[k3] = v3
```
</td><td>
```go
m := map[T1]T2{
k1: v1,
k2: v2,
k3: v3,
}
```
</td></tr>
</tbody></table>
The basic rule of thumb is to use map literals when adding a fixed set of
elements at initialization time, otherwise use `make` (and specify a size hint
if available).
================================================
FILE: src/mutex-zero-value.md
================================================
# Zero-value Mutexes are Valid
The zero-value of `sync.Mutex` and `sync.RWMutex` is valid, so you almost
never need a pointer to a mutex.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
mu := new(sync.Mutex)
mu.Lock()
```
</td><td>
```go
var mu sync.Mutex
mu.Lock()
```
</td></tr>
</tbody></table>
If you use a struct by pointer, then the mutex should be a non-pointer field on
it. Do not embed the mutex on the struct, even if the struct is not exported.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
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]
}
```
</td><td>
```go
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]
}
```
</td></tr>
<tr><td>
The `Mutex` field, and the `Lock` and `Unlock` methods are unintentionally part
of the exported API of `SMap`.
</td><td>
The mutex and its methods are implementation details of `SMap` hidden from its
callers.
</td></tr>
</tbody></table>
================================================
FILE: src/nest-less.md
================================================
# Reduce Nesting
Code should reduce nesting where possible by handling error cases/special
conditions first and returning early or continuing the loop. Reduce the amount
of code that is nested multiple levels.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
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)
}
}
```
</td><td>
```go
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()
}
```
</td></tr>
</tbody></table>
================================================
FILE: src/package-name.md
================================================
# Package Names
When naming packages, choose a name that is:
- All lower-case. No capitals or underscores.
- Does not need to be renamed using named imports at most call sites.
- Short and succinct. Remember that the name is identified in full at every call
site.
- Not plural. For example, `net/url`, not `net/urls`.
- Not "common", "util", "shared", or "lib". These are bad, uninformative names.
See also [Package Names] and [Style guideline for Go packages].
[Package Names]: https://go.dev/blog/package-names
[Style guideline for Go packages]: https://rakyll.org/style-packages/
================================================
FILE: src/panic.md
================================================
# Don't Panic
Code running in production must avoid panics. Panics are a major source of
[cascading failures]. If an error occurs, the function must return an error and
allow the caller to decide how to handle it.
[cascading failures]: https://en.wikipedia.org/wiki/Cascading_failure
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func run(args []string) {
if len(args) == 0 {
panic("an argument is required")
}
// ...
}
func main() {
run(os.Args[1:])
}
```
</td><td>
```go
func run(args []string) error {
if len(args) == 0 {
return errors.New("an argument is required")
}
// ...
return nil
}
func main() {
if err := run(os.Args[1:]); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
```
</td></tr>
</tbody></table>
Panic/recover is not an error handling strategy. A program must panic only when
something irrecoverable happens such as a nil dereference. An exception to this is
program initialization: bad things at program startup that should abort the
program may cause panic.
```go
var _statusTemplate = template.Must(template.New("name").Parse("_statusHTML"))
```
Even in tests, prefer `t.Fatal` or `t.FailNow` over panics to ensure that the
test is marked as failed.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// func TestFoo(t *testing.T)
f, err := os.CreateTemp("", "test")
if err != nil {
panic("failed to set up test")
}
```
</td><td>
```go
// func TestFoo(t *testing.T)
f, err := os.CreateTemp("", "test")
if err != nil {
t.Fatal("failed to set up test")
}
```
</td></tr>
</tbody></table>
================================================
FILE: src/param-naked.md
================================================
# Avoid Naked Parameters
Naked parameters in function calls can hurt readability. Add C-style comments
(`/* ... */`) for parameter names when their meaning is not obvious.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// func printInfo(name string, isLocal, done bool)
printInfo("foo", true, true)
```
</td><td>
```go
// func printInfo(name string, isLocal, done bool)
printInfo("foo", true /* isLocal */, true /* done */)
```
</td></tr>
</tbody></table>
Better yet, replace naked `bool` types with custom types for more readable and
type-safe code. This allows more than just two states (true/false) for that
parameter in the future.
```go
type Region int
const (
UnknownRegion Region = iota
Local
)
type Status int
const (
StatusReady Status = iota + 1
StatusDone
// Maybe we will have a StatusInProgress in the future.
)
func printInfo(name string, region Region, status Status)
```
================================================
FILE: src/performance.md
================================================
# Performance
Performance-specific guidelines apply only to the hot path.
================================================
FILE: src/preface.txt
================================================
<!--
This file was generated by stitchmd. DO NOT EDIT.
To make changes, edit the files in the "src" directory.
-->
<!-- markdownlint-disable MD033 -->
================================================
FILE: src/printf-const.md
================================================
# Format Strings outside Printf
If you declare format strings for `Printf`-style functions outside a string
literal, make them `const` values.
This helps `go vet` perform static analysis of the format string.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
msg := "unexpected values %v, %v\n"
fmt.Printf(msg, 1, 2)
```
</td><td>
```go
const msg = "unexpected values %v, %v\n"
fmt.Printf(msg, 1, 2)
```
</td></tr>
</tbody></table>
================================================
FILE: src/printf-name.md
================================================
# Naming Printf-style Functions
When you declare a `Printf`-style function, make sure that `go vet` can detect
it and check the format string.
This means that you should use predefined `Printf`-style function
names if possible. `go vet` will check these by default. See [Printf family]
for more information.
[Printf family]: https://pkg.go.dev/cmd/vet#hdr-Printf_family
If using the predefined names is not an option, end the name you choose with
f: `Wrapf`, not `Wrap`. `go vet` can be asked to check specific `Printf`-style
names but they must end with f.
```shell
go vet -printfuncs=wrapf,statusf
```
See also [go vet: Printf family check].
[go vet: Printf family check]: https://kuzminva.wordpress.com/2017/11/07/go-vet-printf-family-check/
================================================
FILE: src/slice-nil.md
================================================
# nil is a valid slice
`nil` is a valid slice of length 0. This means that,
- You should not return a slice of length zero explicitly. Return `nil`
instead.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
if x == "" {
return []int{}
}
```
</td><td>
```go
if x == "" {
return nil
}
```
</td></tr>
</tbody></table>
- To check if a slice is empty, always use `len(s) == 0`. Do not check for
`nil`.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func isEmpty(s []string) bool {
return s == nil
}
```
</td><td>
```go
func isEmpty(s []string) bool {
return len(s) == 0
}
```
</td></tr>
</tbody></table>
- The zero value (a slice declared with `var`) is usable immediately without
`make()`.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
nums := []int{}
// or, nums := make([]int)
if add1 {
nums = append(nums, 1)
}
if add2 {
nums = append(nums, 2)
}
```
</td><td>
```go
var nums []int
if add1 {
nums = append(nums, 1)
}
if add2 {
nums = append(nums, 2)
}
```
</td></tr>
</tbody></table>
Remember that, while it is a valid slice, a nil slice is not equivalent to an
allocated slice of length 0 - one is nil and the other is not - and the two may
be treated differently in different situations (such as serialization).
================================================
FILE: src/strconv.md
================================================
# Prefer strconv over fmt
When converting primitives to/from strings, `strconv` is faster than
`fmt`.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
for i := 0; i < b.N; i++ {
s := fmt.Sprint(rand.Int())
}
```
</td><td>
```go
for i := 0; i < b.N; i++ {
s := strconv.Itoa(rand.Int())
}
```
</td></tr>
<tr><td>
```plain
BenchmarkFmtSprint-4 143 ns/op 2 allocs/op
```
</td><td>
```plain
BenchmarkStrconv-4 64.2 ns/op 1 allocs/op
```
</td></tr>
</tbody></table>
================================================
FILE: src/string-byte-slice.md
================================================
# Avoid repeated string-to-byte conversions
Do not create byte slices from a fixed string repeatedly. Instead, perform the
conversion once and capture the result.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
for i := 0; i < b.N; i++ {
w.Write([]byte("Hello world"))
}
```
</td><td>
```go
data := []byte("Hello world")
for i := 0; i < b.N; i++ {
w.Write(data)
}
```
</td></tr>
<tr><td>
```plain
BenchmarkBad-4 50000000 22.2 ns/op
```
</td><td>
```plain
BenchmarkGood-4 500000000 3.25 ns/op
```
</td></tr>
</tbody></table>
================================================
FILE: src/string-escape.md
================================================
# Use Raw String Literals to Avoid Escaping
Go supports [raw string literals](https://go.dev/ref/spec#raw_string_lit),
which can span multiple lines and include quotes. Use these to avoid
hand-escaped strings which are much harder to read.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
wantError := "unknown name:\"test\""
```
</td><td>
```go
wantError := `unknown error:"test"`
```
</td></tr>
</tbody></table>
================================================
FILE: src/struct-embed.md
================================================
# Embedding in Structs
Embedded types should be at the top of the field list of a
struct, and there must be an empty line separating embedded fields from regular
fields.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Client struct {
version int
http.Client
}
```
</td><td>
```go
type Client struct {
http.Client
version int
}
```
</td></tr>
</tbody></table>
Embedding should provide tangible benefit, like adding or augmenting
functionality in a semantically-appropriate way. It should do this with zero
adverse user-facing effects (see also: [Avoid Embedding Types in Public Structs](embed-public.md)).
Exception: Mutexes should not be embedded, even on unexported types. See also: [Zero-value Mutexes are Valid](mutex-zero-value.md).
Embedding **should not**:
- Be purely cosmetic or convenience-oriented.
- Make outer types more difficult to construct or use.
- Affect outer types' zero values. If the outer type has a useful zero value, it
should still have a useful zero value after embedding the inner type.
- Expose unrelated functions or fields from the outer type as a side-effect of
embedding the inner type.
- Expose unexported types.
- Affect outer types' copy semantics.
- Change the outer type's API or type semantics.
- Embed a non-canonical form of the inner type.
- Expose implementation details of the outer type.
- Allow users to observe or control type internals.
- Change the general behavior of inner functions through wrapping in a way that
would reasonably surprise users.
Simply put, embed consciously and intentionally. A good litmus test is, "would
all of these exported inner methods/fields be added directly to the outer type";
if the answer is "some" or "no", don't embed the inner type - use a field
instead.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type A struct {
// Bad: A.Lock() and A.Unlock() are
// now available, provide no
// functional benefit, and allow
// users to control details about
// the internals of A.
sync.Mutex
}
```
</td><td>
```go
type countingWriteCloser struct {
// Good: Write() is provided at this
// outer layer for a specific
// purpose, and delegates work
// to the inner type's Write().
io.WriteCloser
count int
}
func (w *countingWriteCloser) Write(bs []byte) (int, error) {
w.count += len(bs)
return w.WriteCloser.Write(bs)
}
```
</td></tr>
<tr><td>
```go
type Book struct {
// Bad: pointer changes zero value usefulness
io.ReadWriter
// other fields
}
// later
var b Book
b.Read(...) // panic: nil pointer
b.String() // panic: nil pointer
b.Write(...) // panic: nil pointer
```
</td><td>
```go
type Book struct {
// Good: has useful zero value
bytes.Buffer
// other fields
}
// later
var b Book
b.Read(...) // ok
b.String() // ok
b.Write(...) // ok
```
</td></tr>
<tr><td>
```go
type Client struct {
sync.Mutex
sync.WaitGroup
bytes.Buffer
url.URL
}
```
</td><td>
```go
type Client struct {
mtx sync.Mutex
wg sync.WaitGroup
buf bytes.Buffer
url url.URL
}
```
</td></tr>
</tbody></table>
================================================
FILE: src/struct-field-key.md
================================================
# Use Field Names to Initialize Structs
You should almost always specify field names when initializing structs. This is
now enforced by [`go vet`].
[`go vet`]: https://pkg.go.dev/cmd/vet
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
k := User{"John", "Doe", true}
```
</td><td>
```go
k := User{
FirstName: "John",
LastName: "Doe",
Admin: true,
}
```
</td></tr>
</tbody></table>
Exception: Field names *may* be omitted in test tables when there are 3 or
fewer fields.
```go
tests := []struct{
op Operation
want string
}{
{Add, "add"},
{Subtract, "subtract"},
}
```
================================================
FILE: src/struct-field-zero.md
================================================
# Omit Zero Value Fields in Structs
When initializing structs with field names, omit fields that have zero values
unless they provide meaningful context. Otherwise, let Go set these to zero
values automatically.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
user := User{
FirstName: "John",
LastName: "Doe",
MiddleName: "",
Admin: false,
}
```
</td><td>
```go
user := User{
FirstName: "John",
LastName: "Doe",
}
```
</td></tr>
</tbody></table>
This helps reduce noise for readers by omitting values that are default in
that context. Only meaningful values are specified.
Include zero values where field names provide meaningful context. For example,
test cases in [Test Tables](test-table.md) can benefit from names of fields
even when they are zero-valued.
```go
tests := []struct{
give string
want int
}{
{give: "0", want: 0},
// ...
}
```
================================================
FILE: src/struct-pointer.md
================================================
# Initializing Struct References
Use `&T{}` instead of `new(T)` when initializing struct references so that it
is consistent with the struct initialization.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
sval := T{Name: "foo"}
// inconsistent
sptr := new(T)
sptr.Name = "bar"
```
</td><td>
```go
sval := T{Name: "foo"}
sptr := &T{Name: "bar"}
```
</td></tr>
</tbody></table>
================================================
FILE: src/struct-tag.md
================================================
# Use field tags in marshaled structs
Any struct field that is marshaled into JSON, YAML,
or other formats that support tag-based field naming
should be annotated with the relevant tag.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
type Stock struct {
Price int
Name string
}
bytes, err := json.Marshal(Stock{
Price: 137,
Name: "UBER",
})
```
</td><td>
```go
type Stock struct {
Price int `json:"price"`
Name string `json:"name"`
// Safe to rename Name to Symbol.
}
bytes, err := json.Marshal(Stock{
Price: 137,
Name: "UBER",
})
```
</td></tr>
</tbody></table>
Rationale:
The serialized form of the structure is a contract between different systems.
Changes to the structure of the serialized form--including field names--break
this contract. Specifying field names inside tags makes the contract explicit,
and it guards against accidentally breaking the contract by refactoring or
renaming fields.
================================================
FILE: src/struct-zero.md
================================================
# Use `var` for Zero Value Structs
When all the fields of a struct are omitted in a declaration, use the `var`
form to declare the struct.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
user := User{}
```
</td><td>
```go
var user User
```
</td></tr>
</tbody></table>
This differentiates zero valued structs from those with non-zero fields
similar to the distinction created for [map initialization](map-init.md), and matches how
we prefer to [declare empty slices].
[declare empty slices]: https://go.dev/wiki/CodeReviewComments#declaring-empty-slices
================================================
FILE: src/test-table.md
================================================
# Test Tables
Table-driven tests with [subtests] can be a helpful pattern for writing tests
to avoid duplicating code when the core test logic is repetitive.
If a system under test needs to be tested against _multiple conditions_ where
certain parts of the the inputs and outputs change, a table-driven test should
be used to reduce redundancy and improve readability.
[subtests]: https://go.dev/blog/subtests
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// 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)
```
</td><td>
```go
// 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)
})
}
```
</td></tr>
</tbody></table>
Test tables make it easier to add context to error messages, reduce duplicate
logic, and add new test cases.
We follow the convention that the slice of structs is referred to as `tests`
and each test case `tt`. Further, we encourage explicating the input and output
values for each test case with `give` and `want` prefixes.
```go
tests := []struct{
give string
wantHost string
wantPort string
}{
// ...
}
for _, tt := range tests {
// ...
}
```
## Avoid Unnecessary Complexity in Table Tests
Table tests can be difficult to read and maintain if the subtests contain conditional
assertions or other branching logic. Table tests should **NOT** be used whenever
there needs to be complex or conditional logic inside subtests (i.e. complex logic inside the `for` loop).
Large, complex table tests harm readability and maintainability because test readers may
have difficulty debugging test failures that occur.
Table tests like this should be split into either multiple test tables or multiple
individual `Test...` functions.
Some ideals to aim for are:
* Focus on the narrowest unit of behavior
* Minimize "test depth", and avoid conditional assertions (see below)
* Ensure that all table fields are used in all tests
* Ensure that all test logic runs for all table cases
In this context, "test depth" means "within a given test, the number of
successive assertions that require previous assertions to hold" (similar
to cyclomatic complexity).
Having "shallower" tests means that there are fewer relationships between
assertions and, more importantly, that those assertions are less likely
to be conditional by default.
Concretely, table tests can become confusing and difficult to read if they use multiple branching
pathways (e.g. `shouldError`, `expectCall`, etc.), use many `if` statements for
specific mock expectations (e.g. `shouldCallFoo`), or place functions inside the
table (e.g. `setupMocks func(*FooMock)`).
However, when testing behavior that only
changes based on changed input, it may be preferable to group similar cases
together in a table test to better illustrate how behavior changes across all inputs,
rather than splitting otherwise comparable units into separate tests
and making them harder to compare and contrast.
If the test body is short and straightforward,
it's acceptable to have a single branching pathway for success versus failure cases
with a table field like `shouldErr` to specify error expectations.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func TestComplicatedTable(t *testing.T) {
tests := []struct {
give string
want string
wantErr error
shouldCallX bool
shouldCallY bool
giveXResponse string
giveXErr error
giveYResponse string
giveYErr error
}{
// ...
}
for _, tt := range tests {
t.Run(tt.give, func(t *testing.T) {
// setup mocks
ctrl := gomock.NewController(t)
xMock := xmock.NewMockX(ctrl)
if tt.shouldCallX {
xMock.EXPECT().Call().Return(
tt.giveXResponse, tt.giveXErr,
)
}
yMock := ymock.NewMockY(ctrl)
if tt.shouldCallY {
yMock.EXPECT().Call().Return(
tt.giveYResponse, tt.giveYErr,
)
}
got, err := DoComplexThing(tt.give, xMock, yMock)
// verify results
if tt.wantErr != nil {
require.EqualError(t, err, tt.wantErr)
return
}
require.NoError(t, err)
assert.Equal(t, want, got)
})
}
}
```
</td><td>
```go
func TestShouldCallX(t *testing.T) {
// setup mocks
ctrl := gomock.NewController(t)
xMock := xmock.NewMockX(ctrl)
xMock.EXPECT().Call().Return("XResponse", nil)
yMock := ymock.NewMockY(ctrl)
got, err := DoComplexThing("inputX", xMock, yMock)
require.NoError(t, err)
assert.Equal(t, "want", got)
}
func TestShouldCallYAndFail(t *testing.T) {
// setup mocks
ctrl := gomock.NewController(t)
xMock := xmock.NewMockX(ctrl)
yMock := ymock.NewMockY(ctrl)
yMock.EXPECT().Call().Return("YResponse", nil)
_, err := DoComplexThing("inputY", xMock, yMock)
assert.EqualError(t, err, "Y failed")
}
```
</td></tr>
</tbody></table>
This complexity makes it more difficult to change, understand, and prove the
correctness of the test.
While there are no strict guidelines, readability and maintainability should
always be top-of-mind when deciding between Table Tests versus separate tests
for multiple inputs/outputs to a system.
## Parallel Tests
Parallel tests, like some specialized loops (for example, those that spawn
goroutines or capture references as part of the loop body),
must take care to explicitly assign loop variables within the loop's scope to
ensure that they hold the expected values.
```go
tests := []struct{
give string
// ...
}{
// ...
}
for _, tt := range tests {
tt := tt // for t.Parallel
t.Run(tt.give, func(t *testing.T) {
t.Parallel()
// ...
})
}
```
In the example above, we must declare a `tt` variable scoped to the loop
iteration because of the use of `t.Parallel()` below.
If we do not do that, most or all tests will receive an unexpected value for
`tt`, or a value that changes as they're running.
<!-- TODO: Explain how to use _test packages. -->
================================================
FILE: src/time.md
================================================
# Use `"time"` to handle time
Time is complicated. Incorrect assumptions often made about time include the
following.
1. A day has 24 hours
2. An hour has 60 minutes
3. A week has 7 days
4. A year has 365 days
5. [And a lot more](https://infiniteundo.com/post/25326999628/falsehoods-programmers-believe-about-time)
For example, *1* means that adding 24 hours to a time instant will not always
yield a new calendar day.
Therefore, always use the [`"time"`] package when dealing with time because it
helps deal with these incorrect assumptions in a safer, more accurate manner.
[`"time"`]: https://pkg.go.dev/time
## Use `time.Time` for instants of time
Use [`time.Time`] when dealing with instants of time, and the methods on
`time.Time` when comparing, adding, or subtracting time.
[`time.Time`]: https://pkg.go.dev/time#Time
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func isActive(now, start, stop int) bool {
return start <= now && now < stop
}
```
</td><td>
```go
func isActive(now, start, stop time.Time) bool {
return (start.Before(now) || start.Equal(now)) && now.Before(stop)
}
```
</td></tr>
</tbody></table>
## Use `time.Duration` for periods of time
Use [`time.Duration`] when dealing with periods of time.
[`time.Duration`]: https://pkg.go.dev/time#Duration
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func poll(delay int) {
for {
// ...
time.Sleep(time.Duration(delay) * time.Millisecond)
}
}
poll(10) // was it seconds or milliseconds?
```
</td><td>
```go
func poll(delay time.Duration) {
for {
// ...
time.Sleep(delay)
}
}
poll(10*time.Second)
```
</td></tr>
</tbody></table>
Going back to the example of adding 24 hours to a time instant, the method we
use to add time depends on intent. If we want the same time of the day, but on
the next calendar day, we should use [`Time.AddDate`]. However, if we want an
instant of time guaranteed to be 24 hours after the previous time, we should
use [`Time.Add`].
[`Time.AddDate`]: https://pkg.go.dev/time#Time.AddDate
[`Time.Add`]: https://pkg.go.dev/time#Time.Add
```go
newDay := t.AddDate(0 /* years */, 0 /* months */, 1 /* days */)
maybeNewDay := t.Add(24 * time.Hour)
```
## Use `time.Time` and `time.Duration` with external systems
Use `time.Duration` and `time.Time` in interactions with external systems when
possible. For example:
- Command-line flags: [`flag`] supports `time.Duration` via
[`time.ParseDuration`]
- JSON: [`encoding/json`] supports encoding `time.Time` as an [RFC 3339]
string via its [`UnmarshalJSON` method]
- SQL: [`database/sql`] supports converting `DATETIME` or `TIMESTAMP` columns
into `time.Time` and back if the underlying driver supports it
- YAML: [`gopkg.in/yaml.v2`] supports `time.Time` as an [RFC 3339] string, and
`time.Duration` via [`time.ParseDuration`].
[`flag`]: https://pkg.go.dev/flag
[`time.ParseDuration`]: https://pkg.go.dev/time#ParseDuration
[`encoding/json`]: https://pkg.go.dev/encoding/json
[RFC 3339]: https://tools.ietf.org/html/rfc3339
[`UnmarshalJSON` method]: https://pkg.go.dev/time#Time.UnmarshalJSON
[`database/sql`]: https://pkg.go.dev/database/sql
[`gopkg.in/yaml.v2`]: https://pkg.go.dev/gopkg.in/yaml.v2
When it is not possible to use `time.Duration` in these interactions, use
`int` or `float64` and include the unit in the name of the field.
For example, since `encoding/json` does not support `time.Duration`, the unit
is included in the name of the field.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
// {"interval": 2}
type Config struct {
Interval int `json:"interval"`
}
```
</td><td>
```go
// {"intervalMillis": 2000}
type Config struct {
IntervalMillis int `json:"intervalMillis"`
}
```
</td></tr>
</tbody></table>
When it is not possible to use `time.Time` in these interactions, unless an
alternative is agreed upon, use `string` and format timestamps as defined in
[RFC 3339]. This format is used by default by [`Time.UnmarshalText`] and is
available for use in `Time.Format` and `time.Parse` via [`time.RFC3339`].
[`Time.UnmarshalText`]: https://pkg.go.dev/time#Time.UnmarshalText
[`time.RFC3339`]: https://pkg.go.dev/time#RFC3339
Although this tends to not be a problem in practice, keep in mind that the
`"time"` package does not support parsing timestamps with leap seconds
([8728]), nor does it account for leap seconds in calculations ([15190]). If
you compare two instants of time, the difference will not include the leap
seconds that may have occurred between those two instants.
[8728]: https://github.com/golang/go/issues/8728
[15190]: https://github.com/golang/go/issues/15190
================================================
FILE: src/type-assert.md
================================================
# Handle Type Assertion Failures
The single return value form of a [type assertion] will panic on an incorrect
type. Therefore, always use the "comma ok" idiom.
[type assertion]: https://go.dev/ref/spec#Type_assertions
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
t := i.(string)
```
</td><td>
```go
t, ok := i.(string)
if !ok {
// handle the error gracefully
}
```
</td></tr>
</tbody></table>
<!-- TODO: There are a few situations where the single assignment form is
fine. -->
================================================
FILE: src/var-decl.md
================================================
# Local Variable Declarations
Short variable declarations (`:=`) should be used if a variable is being set to
some value explicitly.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
var s = "foo"
```
</td><td>
```go
s := "foo"
```
</td></tr>
</tbody></table>
However, there are cases where the default value is clearer when the `var`
keyword is used. [Declaring Empty Slices], for example.
[Declaring Empty Slices]: https://go.dev/wiki/CodeReviewComments#declaring-empty-slices
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
func f(list []int) {
filtered := []int{}
for _, v := range list {
if v > 10 {
filtered = append(filtered, v)
}
}
}
```
</td><td>
```go
func f(list []int) {
var filtered []int
for _, v := range list {
if v > 10 {
filtered = append(filtered, v)
}
}
}
```
</td></tr>
</tbody></table>
================================================
FILE: src/var-scope.md
================================================
# Reduce Scope of Variables
Where possible, reduce scope of variables and constants. Do not reduce the scope if it
conflicts with [Reduce Nesting](nest-less.md).
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
err := os.WriteFile(name, data, 0644)
if err != nil {
return err
}
```
</td><td>
```go
if err := os.WriteFile(name, data, 0644); err != nil {
return err
}
```
</td></tr>
</tbody></table>
If you need a result of a function call outside of the if, then you should not
try to reduce the scope.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
if data, err := os.ReadFile(name); err == nil {
err = cfg.Decode(data)
if err != nil {
return err
}
fmt.Println(cfg)
return nil
} else {
return err
}
```
</td><td>
```go
data, err := os.ReadFile(name)
if err != nil {
return err
}
if err := cfg.Decode(data); err != nil {
return err
}
fmt.Println(cfg)
return nil
```
</td></tr>
</tbody></table>
Constants do not need to be global unless they are used in multiple functions or files
or are part of an external contract of the package.
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>
```go
const (
_defaultPort = 8080
_defaultUser = "user"
)
func Bar() {
fmt.Println("Default port", _defaultPort)
}
```
</td><td>
```go
func Bar() {
const (
defaultPort = 8080
defaultUser = "user"
)
fmt.Println("Default port", defaultPort)
}
```
</td></tr>
</tbody></table>
gitextract_96pgpcf4/
├── .gitignore
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── LICENSE
├── README.md
└── src/
├── README.md
├── SUMMARY.md
├── atomic.md
├── builtin-name.md
├── channel-size.md
├── consistency.md
├── container-capacity.md
├── container-copy.md
├── decl-group.md
├── defer-clean.md
├── else-unnecessary.md
├── embed-public.md
├── enum-start.md
├── error-name.md
├── error-once.md
├── error-type.md
├── error-wrap.md
├── exit-main.md
├── exit-once.md
├── function-name.md
├── function-order.md
├── functional-option.md
├── global-decl.md
├── global-mut.md
├── global-name.md
├── goroutine-exit.md
├── goroutine-forget.md
├── goroutine-init.md
├── import-alias.md
├── import-group.md
├── init.md
├── interface-compliance.md
├── interface-pointer.md
├── interface-receiver.md
├── intro.md
├── line-length.md
├── lint.md
├── map-init.md
├── mutex-zero-value.md
├── nest-less.md
├── package-name.md
├── panic.md
├── param-naked.md
├── performance.md
├── preface.txt
├── printf-const.md
├── printf-name.md
├── slice-nil.md
├── strconv.md
├── string-byte-slice.md
├── string-escape.md
├── struct-embed.md
├── struct-field-key.md
├── struct-field-zero.md
├── struct-pointer.md
├── struct-tag.md
├── struct-zero.md
├── test-table.md
├── time.md
├── type-assert.md
├── var-decl.md
└── var-scope.md
Condensed preview — 67 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (175K chars).
[
{
"path": ".gitignore",
"chars": 5,
"preview": ".idea"
},
{
"path": "CHANGELOG.md",
"chars": 308,
"preview": "\n# 2020 年 1 月 30 日\n\n- 建议在处理时间时使用 “time” 包。\n\n# 2020 年 1 月 25 日\n\n- 添加有关在公共结构中嵌入类型的指导。\n\n# 2019 年 12 月 17 日\n\n- 函数选项：推荐 “Opti"
},
{
"path": "CODE_OF_CONDUCT.md",
"chars": 3352,
"preview": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nIn the interest of fostering an open and welcoming environment, w"
},
{
"path": "LICENSE",
"chars": 10173,
"preview": " Apache License\n Version 2.0, January 2004\n "
},
{
"path": "README.md",
"chars": 61492,
"preview": "<!--\n\nEditing this document:\n\n- Discuss all changes in GitHub issues first.\n- Update the table of contents as new sectio"
},
{
"path": "src/README.md",
"chars": 116,
"preview": "The contents of this directory are used to generate the top-level style.md.\nThe layout is controlled by SUMMARY.md.\n"
},
{
"path": "src/SUMMARY.md",
"chars": 2842,
"preview": "# Uber Go Style Guide\n\n- [Introduction](intro.md)\n- Guidelines\n - [Pointers to Interfaces](interface-pointer.md)\n - [V"
},
{
"path": "src/atomic.md",
"chars": 1075,
"preview": "# Use go.uber.org/atomic\n\nAtomic operations with the [sync/atomic] package operate on the raw types\n(`int32`, `int64`, e"
},
{
"path": "src/builtin-name.md",
"chars": 1871,
"preview": "# Avoid Using Built-In Names\n\nThe Go [language specification] outlines several built-in,\n[predeclared identifiers] that "
},
{
"path": "src/channel-size.md",
"chars": 657,
"preview": "# Channel Size is One or None\n\nChannels should usually have a size of one or be unbuffered. By default,\nchannels are unb"
},
{
"path": "src/consistency.md",
"chars": 848,
"preview": "# Be Consistent\n\nSome of the guidelines outlined in this document can be evaluated objectively;\nothers are situational, "
},
{
"path": "src/container-capacity.md",
"chars": 2465,
"preview": "# Prefer Specifying Container Capacity\n\nSpecify container capacity where possible in order to allocate memory for the\nco"
},
{
"path": "src/container-copy.md",
"chars": 1716,
"preview": "# Copy Slices and Maps at Boundaries\n\nSlices and maps contain pointers to the underlying data so be wary of scenarios\nwh"
},
{
"path": "src/decl-group.md",
"chars": 2161,
"preview": "# Group Similar Declarations\n\nGo supports grouping similar declarations.\n\n<table>\n<thead><tr><th>Bad</th><th>Good</th></"
},
{
"path": "src/defer-clean.md",
"chars": 874,
"preview": "# Defer to Clean Up\n\nUse defer to clean up resources such as files and locks.\n\n<table>\n<thead><tr><th>Bad</th><th>Good</"
},
{
"path": "src/else-unnecessary.md",
"chars": 317,
"preview": "# Unnecessary Else\n\nIf a variable is set in both branches of an if, it can be replaced with a\nsingle if.\n\n<table>\n<thead"
},
{
"path": "src/embed-public.md",
"chars": 3309,
"preview": "# Avoid Embedding Types in Public Structs\n\nThese embedded types leak implementation details, inhibit type evolution, and"
},
{
"path": "src/enum-start.md",
"chars": 916,
"preview": "# Start Enums at One\n\nThe standard way of introducing enumerations in Go is to declare a custom type\nand a `const` group"
},
{
"path": "src/error-name.md",
"chars": 1237,
"preview": "# Error Naming\n\nFor error values stored as global variables,\nuse the prefix `Err` or `err` depending on whether they're "
},
{
"path": "src/error-once.md",
"chars": 2530,
"preview": "# Handle Errors Once\n\nWhen a caller receives an error from a callee,\nit can handle it in a variety of different ways\ndep"
},
{
"path": "src/error-type.md",
"chars": 3215,
"preview": "# Error Types\n\nThere are few options for declaring errors.\nConsider the following before picking the option best suited "
},
{
"path": "src/error-wrap.md",
"chars": 2309,
"preview": "# Error Wrapping\n\nThere are three main options for propagating errors if a call fails:\n\n- return the original error as-i"
},
{
"path": "src/exit-main.md",
"chars": 1672,
"preview": "# Exit in Main\n\nGo programs use [`os.Exit`] or [`log.Fatal*`] to exit immediately. (Panicking\nis not a good way to exit "
},
{
"path": "src/exit-once.md",
"chars": 2429,
"preview": "# Exit Once\n\nIf possible, prefer to call `os.Exit` or `log.Fatal` **at most once** in your\n`main()`. If there are multip"
},
{
"path": "src/function-name.md",
"chars": 338,
"preview": "# Function Names\n\nWe follow the Go community's convention of using [MixedCaps for function\nnames]. An exception is made "
},
{
"path": "src/function-order.md",
"chars": 1041,
"preview": "# Function Grouping and Ordering\n\n- Functions should be sorted in rough call order.\n- Functions in a file should be grou"
},
{
"path": "src/functional-option.md",
"chars": 3289,
"preview": "# Functional Options\n\nFunctional options is a pattern in which you declare an opaque `Option` type\nthat records informat"
},
{
"path": "src/global-decl.md",
"chars": 780,
"preview": "# Top-level Variable Declarations\n\nAt the top level, use the standard `var` keyword. Do not specify the type,\nunless it "
},
{
"path": "src/global-mut.md",
"chars": 1087,
"preview": "# Avoid Mutable Globals\n\nAvoid mutating global variables, instead opting for dependency injection.\nThis applies to funct"
},
{
"path": "src/global-name.md",
"chars": 893,
"preview": "# Prefix Unexported Globals with _\n\nPrefix unexported top-level `var`s and `const`s with `_` to make it clear when\nthey "
},
{
"path": "src/goroutine-exit.md",
"chars": 756,
"preview": "# Wait for goroutines to exit\n\nGiven a goroutine spawned by the system,\nthere must be a way to wait for the goroutine to"
},
{
"path": "src/goroutine-forget.md",
"chars": 1803,
"preview": "# Don't fire-and-forget goroutines\n\nGoroutines are lightweight, but they're not free:\nat minimum, they cost memory for t"
},
{
"path": "src/goroutine-init.md",
"chars": 1483,
"preview": "# No goroutines in `init()`\n\n`init()` functions should not spawn goroutines.\nSee also [Avoid init()](init.md).\n\nIf a pac"
},
{
"path": "src/import-alias.md",
"chars": 634,
"preview": "# Import Aliasing\n\nImport aliasing must be used if the package name does not match the last\nelement of the import path.\n"
},
{
"path": "src/import-group.md",
"chars": 452,
"preview": "# Import Group Ordering\n\nThere should be two import groups:\n\n- Standard library\n- Everything else\n\nThis is the grouping "
},
{
"path": "src/init.md",
"chars": 2547,
"preview": "# Avoid `init()`\n\nAvoid `init()` where possible. When `init()` is unavoidable or desirable, code\nshould attempt to:\n\n1. "
},
{
"path": "src/interface-compliance.md",
"chars": 1327,
"preview": "# Verify Interface Compliance\n\nVerify interface compliance at compile time where appropriate. This includes:\n\n- Exported"
},
{
"path": "src/interface-pointer.md",
"chars": 505,
"preview": "# Pointers to Interfaces\n\nYou almost never need a pointer to an interface. You should be passing\ninterfaces as values—th"
},
{
"path": "src/interface-receiver.md",
"chars": 1628,
"preview": "# Receivers and Interfaces\n\nMethods with value receivers can be called on pointers as well as values.\nMethods with point"
},
{
"path": "src/intro.md",
"chars": 1529,
"preview": "# Introduction\n\nStyles are the conventions that govern our code. The term style is a bit of a\nmisnomer, since these conv"
},
{
"path": "src/line-length.md",
"chars": 308,
"preview": "# Avoid overly long lines\n\nAvoid lines of code that require readers to scroll horizontally\nor turn their heads too much."
},
{
"path": "src/lint.md",
"chars": 1478,
"preview": "# Linting\n\nMore importantly than any \"blessed\" set of linters, lint consistently across a\ncodebase.\n\nWe recommend using "
},
{
"path": "src/map-init.md",
"chars": 1418,
"preview": "# Initializing Maps\n\nPrefer `make(..)` for empty maps, and maps populated\nprogrammatically. This makes map initializatio"
},
{
"path": "src/mutex-zero-value.md",
"chars": 1341,
"preview": "# Zero-value Mutexes are Valid\n\nThe zero-value of `sync.Mutex` and `sync.RWMutex` is valid, so you almost\nnever need a p"
},
{
"path": "src/nest-less.md",
"chars": 729,
"preview": "# Reduce Nesting\n\nCode should reduce nesting where possible by handling error cases/special\nconditions first and returni"
},
{
"path": "src/package-name.md",
"chars": 593,
"preview": "# Package Names\n\nWhen naming packages, choose a name that is:\n\n- All lower-case. No capitals or underscores.\n- Does not "
},
{
"path": "src/panic.md",
"chars": 1641,
"preview": "# Don't Panic\n\nCode running in production must avoid panics. Panics are a major source of\n[cascading failures]. If an er"
},
{
"path": "src/param-naked.md",
"chars": 945,
"preview": "# Avoid Naked Parameters\n\nNaked parameters in function calls can hurt readability. Add C-style comments\n(`/* ... */`) fo"
},
{
"path": "src/performance.md",
"chars": 75,
"preview": "# Performance\n\nPerformance-specific guidelines apply only to the hot path.\n"
},
{
"path": "src/preface.txt",
"chars": 157,
"preview": "<!--\n This file was generated by stitchmd. DO NOT EDIT.\n To make changes, edit the files in the \"src\" directory.\n-->\n\n"
},
{
"path": "src/printf-const.md",
"chars": 470,
"preview": "# Format Strings outside Printf\n\nIf you declare format strings for `Printf`-style functions outside a string\nliteral, ma"
},
{
"path": "src/printf-name.md",
"chars": 756,
"preview": "# Naming Printf-style Functions\n\nWhen you declare a `Printf`-style function, make sure that `go vet` can detect\nit and c"
},
{
"path": "src/slice-nil.md",
"chars": 1478,
"preview": "# nil is a valid slice\n\n`nil` is a valid slice of length 0. This means that,\n\n- You should not return a slice of length "
},
{
"path": "src/strconv.md",
"chars": 518,
"preview": "# Prefer strconv over fmt\n\nWhen converting primitives to/from strings, `strconv` is faster than\n`fmt`.\n\n<table>\n<thead><"
},
{
"path": "src/string-byte-slice.md",
"chars": 578,
"preview": "# Avoid repeated string-to-byte conversions\n\nDo not create byte slices from a fixed string repeatedly. Instead, perform "
},
{
"path": "src/string-escape.md",
"chars": 452,
"preview": "# Use Raw String Literals to Avoid Escaping\n\nGo supports [raw string literals](https://go.dev/ref/spec#raw_string_lit),\n"
},
{
"path": "src/struct-embed.md",
"chars": 3234,
"preview": "# Embedding in Structs\n\nEmbedded types should be at the top of the field list of a\nstruct, and there must be an empty li"
},
{
"path": "src/struct-field-key.md",
"chars": 630,
"preview": "# Use Field Names to Initialize Structs\n\nYou should almost always specify field names when initializing structs. This is"
},
{
"path": "src/struct-field-zero.md",
"chars": 906,
"preview": "# Omit Zero Value Fields in Structs\n\nWhen initializing structs with field names, omit fields that have zero values\nunles"
},
{
"path": "src/struct-pointer.md",
"chars": 417,
"preview": "# Initializing Struct References\n\nUse `&T{}` instead of `new(T)` when initializing struct references so that it\nis consi"
},
{
"path": "src/struct-tag.md",
"chars": 968,
"preview": "# Use field tags in marshaled structs\n\nAny struct field that is marshaled into JSON, YAML,\nor other formats that support"
},
{
"path": "src/struct-zero.md",
"chars": 596,
"preview": "# Use `var` for Zero Value Structs\n\nWhen all the fields of a struct are omitted in a declaration, use the `var`\nform to "
},
{
"path": "src/test-table.md",
"chars": 7105,
"preview": "# Test Tables\n\nTable-driven tests with [subtests] can be a helpful pattern for writing tests\nto avoid duplicating code w"
},
{
"path": "src/time.md",
"chars": 4752,
"preview": "# Use `\"time\"` to handle time\n\nTime is complicated. Incorrect assumptions often made about time include the\nfollowing.\n\n"
},
{
"path": "src/type-assert.md",
"chars": 526,
"preview": "# Handle Type Assertion Failures\n\nThe single return value form of a [type assertion] will panic on an incorrect\ntype. Th"
},
{
"path": "src/var-decl.md",
"chars": 927,
"preview": "# Local Variable Declarations\n\nShort variable declarations (`:=`) should be used if a variable is being set to\nsome valu"
},
{
"path": "src/var-scope.md",
"chars": 1511,
"preview": "# Reduce Scope of Variables\n\nWhere possible, reduce scope of variables and constants. Do not reduce the scope if it\nconf"
}
]
About this extraction
This page contains the full source code of the xxjwxc/uber_go_guide_cn GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 67 files (158.7 KB), approximately 53.2k tokens. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.