Uber Go 风格指南

Uber Go Style Guide - Uber Go 风格指南

原文： https://github.com/uber-go/guide/blob/master/style.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.

​ 风格是我们代码遵循的惯例。术语风格有点名不副实，因为这些惯例涵盖的范围远不止源文件格式——gofmt 会为我们处理这些。

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.

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

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 和 Simon Newton 创建，目的是让一些同事快速了解如何使用 Go。多年来，它根据他人的反馈进行了修改。

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:

​ 本文档记录了我们在 Uber 遵循的 Go 代码中的惯用约定。其中许多是 Go 的一般准则，而其他一些则扩展了外部资源：

1. Effective Go 有效的 Go
2. Go Common Mistakes 常见的 Go 错误
3. Go Code Review Comments Go 代码审查评论

We aim for the code samples to be accurate for the two most recent minor versions of Go releases.

​ 我们的目标是让代码示例适用于最近两个次要版本的 Go 版本。

All code should be error-free when run through golint and go vet. We recommend setting up your editor to:

​ 通过 golint 和 go vet 运行时，所有代码都应无错误。我们建议将编辑器设置为：

• Run goimports on save 保存时运行 goimports
• Run golint and go vet to check for errors 运行 golint 和 go vet 以检查错误

You can find information in editor support for Go tools here: https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins

​ 您可以在此处找到有关 Go 工具的编辑器支持信息：https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins

Guidelines 指南

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.

​ 如果希望接口方法修改底层数据，则必须使用指针。

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 作为其 API 契约的一部分，需要实现特定接口的导出类型
• 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 违反接口会破坏用户的情况

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// Bad
type Handler struct {
  // ...
}



func (h *Handler) ServeHTTP(
  w http.ResponseWriter,
  r *http.Request,
) {
  ...
}
// Good
type Handler struct {
  // ...
}

var _ http.Handler = (*Handler)(nil)

func (h *Handler) ServeHTTP(
  w http.ResponseWriter,
  r *http.Request,
) {
  // ...
}

The statement var _ http.Handler = (*Handler)(nil) will fail to compile if *Handler ever stops matching the http.Handler interface.

​ 如果 *Handler 停止匹配 http.Handler 接口，则语句 var _ http.Handler = (*Handler)(nil) 将无法编译。

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.

​ 赋值的右侧应该是断言类型的零值。对于指针类型（如 *Handler ）、切片和映射，这是 nil ，对于结构类型，这是空结构。 接收者和接口

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

type LogHandler struct {
  h   http.Handler
  log *zap.Logger
}

var _ http.Handler = LogHandler{}

func (h LogHandler) ServeHTTP(
  w http.ResponseWriter,
  r *http.Request,
) {
  // ...
}

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.

​ 具有值接收者的方法可以调用指针和值。具有指针接收者的方法只能调用指针或可寻址值。

For example,

​ 例如，

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

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.

​ 同样，即使方法具有值接收者，接口也可以由指针满足。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

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.

​ Effective Go 对指针与值进行了很好的撰写。

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.

​ sync.Mutex 和 sync.RWMutex 的零值有效，因此您几乎不需要指向互斥体的指针。

1
2
3
4
5
6

// Bad
mu := new(sync.Mutex)
mu.Lock()
// Good
var mu sync.Mutex
mu.Lock()

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.

​ 如果您通过指针使用结构体，那么互斥体应该是非指针字段。即使结构体未导出，也不要将互斥体嵌入到结构体中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

// Bad
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]
}
// Good
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]
}

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.

​ 请记住，如果您存储对映射或切片的引用，则用户可以修改您作为参数接收的映射或切片。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

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

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

// Did you mean to modify d1.trips?
trips[0] = ...
// Good
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] = ...

Returning Slices and Maps 返回切片和映射

Similarly, be wary of user modifications to maps or slices exposing internal state.

​ 同样，要小心用户对映射或切片的修改，这些修改会公开内部状态。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// Bad
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()
// Good
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()

Defer to Clean Up 推迟清理

Use defer to clean up resources such as files and locks.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// Bad
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
// Good
p.Lock()
defer p.Unlock()

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

p.count++
return p.count

// more readable

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.

​ 延迟的开销极小，只有当您可以证明函数执行时间以纳秒为单位时才应避免使用延迟。使用延迟的可读性优势值得付出极小的使用成本。对于具有不止简单内存访问的较大方法尤其如此，其中其他计算比 defer 更重要。

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.

​ 通道通常应大小为一或无缓冲。默认情况下，通道无缓冲且大小为零。任何其他大小都必须经过严格审查。考虑如何确定大小，防止通道在负载下填满并阻塞写入器，以及发生这种情况时会发生什么。

1
2
3
4
5
6
7
8

// Bad
// Ought to be enough for anybody!
c := make(chan int, 64)
// Good
// Size of one
c := make(chan int, 1) // or
// Unbuffered channel, size of zero
c := make(chan int)

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.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// Bad
type Operation int

const (
  Add Operation = iota
  Subtract
  Multiply
)

// Add=0, Subtract=1, Multiply=2
// Good
type Operation int

const (
  Add Operation = iota + 1
  Subtract
  Multiply
)

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

There are cases where using the zero value makes sense, for example when the zero value case is the desirable default behavior.

​ 在某些情况下，使用零值是有意义的，例如当零值情况是理想的默认行为时。

1
2
3
4
5
6
7
8
9

type LogOutput int

const (
  LogToStdout LogOutput = iota
  LogToFile
  LogToRemote
)

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

Use "time" to handle time 使用 "time" 处理时间

Time is complicated. Incorrect assumptions often made about time include the following.

​ 时间很复杂。关于时间经常做出的错误假设包括以下内容。

1. A day has 24 hours 一天有 24 小时
2. An hour has 60 minutes 一小时有 60 分钟
3. A week has 7 days 一周有 7 天
4. A year has 365 days 一年有 365 天
5. And a lot more 等等

For example, 1 means that adding 24 hours to a time instant will not always yield a new calendar day.

​ 例如，1 表示将 24 小时添加到时间瞬间并不总是会产生新的日历日。

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" 包，因为它有助于以更安全、更准确的方式处理这些错误假设。

Use time.Time for instants of time 对时间瞬间使用 time.Time

Use time.Time when dealing with instants of time, and the methods on time.Time when comparing, adding, or subtracting time.

​ 在处理时间瞬间时使用 time.Time ，并在比较、添加或减去时间时使用 time.Time 上的方法。

1
2
3
4
5
6
7
8

// Bad
func isActive(now, start, stop int) bool {
  return start <= now && now < stop
}
// Good
func isActive(now, start, stop time.Time) bool {
  return (start.Before(now) || start.Equal(now)) && now.Before(stop)
}

Use time.Duration for periods of time 使用 time.Duration 表示时间段

Use time.Duration when dealing with periods of time.

​ 处理时间段时，请使用 time.Duration 。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// Bad
func poll(delay int) {
  for {
    // ...
    time.Sleep(time.Duration(delay) * time.Millisecond)
  }
}

poll(10) // was it seconds or milliseconds?
// Good
func poll(delay time.Duration) {
  for {
    // ...
    time.Sleep(delay)
  }
}

poll(10*time.Second)

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.

​ 回到将 24 小时添加到时间戳的示例，我们用于添加时间的方法取决于意图。如果我们想要同一天的相同时间，但位于下一个日历日，我们应该使用 Time.AddDate 。但是，如果我们想要一个时间戳，保证在之前的时间之后 24 小时，我们应该使用 Time.Add 。

newDay := t.AddDate(0 /* years */, 0 /* months */, 1 /* days */)
maybeNewDay := t.Add(24 * time.Hour)

Use time.Time and time.Duration with external systems 与外部系统一起使用 time.Time 和 time.Duration

Use time.Duration and time.Time in interactions with external systems when possible. For example:

​ 尽可能在与外部系统的交互中使用 time.Duration 和 time.Time 。例如：

• Command-line flags: flag supports time.Duration via time.ParseDuration 命令行标志： flag 通过 time.ParseDuration 支持 time.Duration
• JSON: encoding/json supports encoding time.Time as an RFC 3339 string via its UnmarshalJSON method JSON: encoding/json 通过其 UnmarshalJSON 方法支持将 time.Time 编码为 RFC 3339 字符串
• SQL: database/sql supports converting DATETIME or TIMESTAMP columns into time.Time and back if the underlying driver supports it SQL: database/sql 支持将 DATETIME 或 TIMESTAMP 列转换为 time.Time ，反之亦然（如果底层驱动程序支持）
• YAML: gopkg.in/yaml.v2 supports time.Time as an RFC 3339 string, and time.Duration via time.ParseDuration. YAML: gopkg.in/yaml.v2 支持 time.Time 作为 RFC 3339 字符串，以及通过 time.ParseDuration 支持 time.Duration 。

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.

​ 如果在这些交互中无法使用 time.Duration ，请使用 int 或 float64 ，并将单位包含在字段名称中。

For example, since encoding/json does not support time.Duration, the unit is included in the name of the field.

​ 例如，由于 encoding/json 不支持 time.Duration ，因此将单位包含在字段名称中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Bad
// {"interval": 2}
type Config struct {
  Interval int `json:"interval"`
}
// Good
// {"intervalMillis": 2000}
type Config struct {
  IntervalMillis int `json:"intervalMillis"`
}

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.Time ，除非另行达成一致，请使用 string ，并将时间戳格式化为 RFC 3339 中定义的格式。此格式默认由 Time.UnmarshalText 使用，并且可通过 time.RFC3339 在 Time.Format 和 time.Parse 中使用。

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.

​ 尽管在实践中这往往不是问题，但请记住， "time" 包不支持解析带闰秒的时间戳 ( 8728)，也不在计算中考虑闰秒 ( 15190)。如果您比较两个时间点，则差值不会包括在这两个时间点之间可能发生的闰秒。

Errors 错误

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. 调用者是否需要匹配错误以便能够处理错误？如果是，我们必须通过声明顶级错误变量或自定义类型来支持 errors.Is 或 errors.As 函数。
• 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. 错误消息是静态字符串还是需要上下文信息的动态字符串？对于前者，我们可以使用 errors.New ，但对于后者，我们必须使用 fmt.Errorf 或自定义错误类型。
• Are we propagating a new error returned by a downstream function? If so, see the section on error wrapping. 我们是否正在传播下游函数返回的新错误？如果是，请参阅错误包装部分。

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.

​ 例如，对于具有静态字符串的错误，请使用 errors.New 。将此错误导出为变量，以支持与 errors.Is 匹配，如果调用方需要匹配并处理此错误。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// No error matching
// 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")
}
// Error matching
// 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")
  }
}

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.

​ 对于具有动态字符串的错误，如果调用方不需要匹配它，请使用 fmt.Errorf ；如果调用方确实需要匹配它，请使用自定义 error 。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

// No error matching
// 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")
}
// Error matching
// 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, &notFound) {
    // handle the error
  } else {
    panic("unknown error")
  }
}

Note that if you export error variables or types from a package, they will become part of the public API of the package.

​ 请注意，如果您从包中导出错误变量或类型，它们将成为包的公共 API 的一部分。

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 使用 fmt.Errorf 和 %w 动词添加上下文
• add context with fmt.Errorf and the %v verb 使用 fmt.Errorf 和 %v 动词添加上下文

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.

​ 使用 fmt.Errorf 为错误添加上下文，根据调用者是否能够匹配并提取根本原因，在 %w 或 %v 动词之间进行选择。

• 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. 如果调用者应该有权访问基础错误，请使用 %w 。对于大多数包装错误来说，这是一个很好的默认值，但请注意，调用者可能会开始依赖此行为。因此，对于包装错误是已知的 var 或类型的情况，请将其作为函数契约的一部分进行记录和测试。
• 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. 使用 %v 混淆基础错误。调用者将无法匹配它，但您可以在需要时在将来切换到 %w 。

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:

​ 在为返回的错误添加上下文时，请避免使用“失败”等短语来保持上下文简洁，这些短语说明了显而易见的事情，并且随着错误在堆栈中渗透而堆积起来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

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

// failed to x: failed to y: failed to create new store: the error
// Good
s, err := store.New()
if err != nil {
    return fmt.Errorf(
        "new store: %w", err)
}

// x: y: new store: the error

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).

​ 但是，一旦错误被发送到另一个系统，就应该清楚消息是一个错误（例如，日志中的 err 标记或“失败”前缀）。

See also Don’t just check errors, handle them gracefully.

​ 另请参阅不要仅仅检查错误，还要妥善处理它们。

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 _.

​ 对于存储为全局变量的错误值，请使用前缀 Err 或 err ，具体取决于它们是否已导出。此指南取代了使用 _ 为未导出的全局变量添加前缀。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

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.

​ 对于自定义错误类型，请改用后缀 Error 。

// 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)
}

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 如果被调用方合约定义了特定错误，则使用 errors.Is 或 errors.As 匹配错误并以不同的方式处理分支
• 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 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:

​ 例如，考虑以下情况：

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.

​ 错误：记录错误并返回错误。堆栈上方的调用者可能会对错误采取类似的操作。这样做会导致应用程序日志中产生大量噪音，而价值却很小。

1
2
3
4
5
6
7

// Bad
u, err := getUser(id)
if err != nil {
  // BAD: See description
  log.Printf("Could not get user %q: %v", id, err)
  return err
}

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.

​ 正确：包装错误并返回错误。堆栈上方的调用者将处理错误。使用 %w 确保它们可以将错误与 errors.Is 或 errors.As （如果相关）匹配。

1
2
3
4
5

// Good
u, err := getUser(id)
if err != nil {
  return fmt.Errorf("get user %q: %w", id, err)
}

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.

​ 正确：记录错误并优雅地降级。如果操作不是严格必需的，我们可以通过从中恢复来提供降级但未中断的体验。

1
2
3
4
5
6

// Good
if err := emitMetrics(); err != nil {
  // Failure to write metrics should not
  // break the application.
  log.Printf("Could not emit metrics: %v", err)
}

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.

​ 正确：匹配错误并优雅地降级。如果被调用者在其契约中定义了特定错误，并且该故障是可恢复的，则匹配该错误情况并优雅地降级。对于所有其他情况，请包装错误并返回错误。堆栈上方的调用者将处理其他错误。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Good
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)
  }
}

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.

​ 类型断言的单一返回值形式会在类型不正确时引发恐慌。因此，始终使用“逗号 ok”习惯用法。

1
2
3
4
5
6
7

// Bad
t := i.(string)
// Good
t, ok := i.(string)
if !ok {
  // handle the error gracefully
}

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.

​ 在生产环境中运行的代码必须避免恐慌。恐慌是级联故障的主要来源。如果发生错误，函数必须返回错误并允许调用者决定如何处理它。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// Bad
func run(args []string) {
  if len(args) == 0 {
    panic("an argument is required")
  }
  // ...
}

func main() {
  run(os.Args[1:])
}
// Good
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)
  }
}

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.

​ 恐慌/恢复不是错误处理策略。程序仅在发生无法恢复的情况（例如 nil 解引用）时才应恐慌。对此的一个例外是程序初始化：程序启动时应中止程序的错误可能会导致恐慌。

1

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.

​ 即使在测试中，也更喜欢 t.Fatal 或 t.FailNow ，而不是恐慌，以确保将测试标记为失败。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// Bad
// func TestFoo(t *testing.T)

f, err := os.CreateTemp("", "test")
if err != nil {
  panic("failed to set up test")
}
// Good
// func TestFoo(t *testing.T)

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

Use go.uber.org/atomic 使用 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.

​ 使用 sync/atomic 包进行原子操作时，操作的是原始类型（ int32 、 int64 等），因此很容易忘记使用原子操作来读取或修改变量。

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 通过隐藏底层类型，为这些操作添加了类型安全性。此外，它还包括一个方便的 atomic.Bool 类型。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// Bad
type foo struct {
  running int32  // atomic
}

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

func (f *foo) isRunning() bool {
  return f.running == 1  // race!
}
// Good
type foo struct {
  running atomic.Bool
}

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

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

Avoid Mutable Globals 避免可变全局变量

Avoid mutating global variables, instead opting for dependency injection. This applies to function pointers as well as other kinds of values.

​ 避免改变全局变量，而选择依赖注入。这适用于函数指针以及其他类型的值。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

// Bad
// sign.go

var _timeNow = time.Now

func sign(msg string) string {
  now := _timeNow()
  return signWithTime(msg, now)
}

// 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))
}
// Good
// 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)
}

// sign_test.go

func TestSigner(t *testing.T) {
  s := newSigner()
  s.now = func() time.Time {
    return someFixedTime
  }

  assert.Equal(t, want, s.Sign(give))
}

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.

​ 假设您使用共享的 AbstractList 实现各种列表类型，请避免在具体列表实现中嵌入 AbstractList 。相反，只手写将委托给抽象列表的具体列表的方法。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

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) {
  // ...
}
// Bad
// ConcreteList is a list of entities.
type ConcreteList struct {
  *AbstractList
}
// Good
// 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)
}

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.

​ Go 允许类型嵌入作为继承和组合之间的折衷方案。外部类型会隐式获取嵌入类型方法的副本。默认情况下，这些方法委托给嵌入实例的相同方法。

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.

​ 即使嵌入兼容的 AbstractList 接口（而不是结构体），也会为开发人员提供更大的灵活性以在将来进行更改，但仍然会泄露具体列表使用抽象实现的细节。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// Bad
// 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
}
// Good
// 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)
}

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.

​ 尽管编写这些委托方法很繁琐，但额外的努力隐藏了实现细节，留出了更多更改机会，还消除了在文档中发现完整 List 接口的间接性。

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.

​ Go 语言规范概述了几个内置的、预声明的标识符，这些标识符不应在 Go 程序中用作名称。

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.

​ 根据上下文，将这些标识符重新用作名称，要么在当前词法作用域（和任何嵌套作用域）内隐藏原始标识符，要么使受影响的代码令人困惑。在最好的情况下，编译器会发出警告；在最坏的情况下，此类代码可能会引入潜在的、难以 grep 的错误。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

// Bad
var error string
// `error` shadows the builtin

// or

func handleErrorMessage(error string) {
    // `error` shadows the builtin
}



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
}
// Good
var errorMessage string
// `error` refers to the builtin

// or

func handleErrorMessage(msg string) {
    // `error` refers to the builtin
}



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
}

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.

​ 请注意，在使用预声明标识符时，编译器不会生成错误，但诸如 go vet 之类的工具应正确指出这些和其他隐藏情况。

Avoid init() 避免 init()

Avoid init() where possible. When init() is unavoidable or desirable, code should attempt to:

​ 尽可能避免 init() 。当 init() 不可避免或合乎需要时，代码应尝试：

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. 避免依赖其他 init() 函数的顺序或副作用。虽然 init() 顺序是众所周知的，但代码可能会发生变化，因此 init() 函数之间的关系可能会使代码变得脆弱且容易出错。
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. 避免 I/O，包括文件系统、网络和系统调用。

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”.

​ 无法满足这些要求的代码可能属于作为 main() （或程序生命周期中的其他位置）的一部分被调用的帮助程序，或者作为 main() 本身的一部分编写。特别是，旨在供其他程序使用的库应特别注意完全确定性，并且不执行“init magic”。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

// Bad
type Foo struct {
    // ...
}

var _defaultFoo Foo

func init() {
    _defaultFoo = Foo{
        // ...
    }
}


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)
}
// Good
var _defaultFoo = Foo{
    // ...
}

// or, better, for testability:

var _defaultFoo = defaultFoo()

func defaultFoo() Foo {
    return Foo{
        // ...
    }
}



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
}

Considering the above, some situations in which init() may be preferable or necessary might include:

​ 考虑到上述情况，可能更可取或必要使用 init() 的一些情况可能包括：

• Complex expressions that cannot be represented as single assignments. 无法表示为单个赋值的复杂表达式。
• Pluggable hooks, such as database/sql dialects, encoding type registries, etc. 可插入的挂钩，例如 database/sql 方言、编码类型注册表等。
• Optimizations to Google Cloud Functions and other forms of deterministic precomputation. 对 Google Cloud Functions 和其他形式的确定性预计算的优化。

Exit in Main 在 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.)

​ Go 程序使用 os.Exit 或 log.Fatal* 立即退出。（引发恐慌不是退出程序的好方法，请不要惊慌。）

Call one of os.Exit or log.Fatal* only in main(). All other functions should return errors to signal failure.

​ 仅在 main() 中调用 os.Exit 或 log.Fatal* 之一。所有其他函数都应返回错误以发出失败信号。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// Bad
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)
}
// Good
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
}

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. 难以测试：退出程序的函数也会退出调用它的测试。这使得函数难以测试，并引入跳过尚未由 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. 跳过的清理：当函数退出程序时，它会跳过使用 defer 语句排队的函数调用。这会增加跳过重要清理任务的风险。

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.

​ 如果可能，最好在 main() 中最多调用 os.Exit 或 log.Fatal 一次。如果有多个导致程序执行停止的错误场景，请将该逻辑放在单独的函数中，并从中返回错误。

This has the effect of shortening your main() function and putting all key business logic into a separate, testable function.

​ 这会缩短 main() 函数，并将所有关键业务逻辑放入单独的可测试函数中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

// Bad
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)
  }

  // ...
}
// Good
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
  }

  // ...
}

The example above uses log.Fatal, but the guidance also applies to os.Exit or any library code that calls os.Exit.

​ 上面的示例使用 log.Fatal ，但该指南也适用于 os.Exit 或任何调用 os.Exit 的库代码。

1
2
3
4
5
6

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.

​ 您可以更改 run() 的签名以满足您的需求。例如，如果您的程序必须使用特定的退出代码退出以表示失败，则 run() 可以返回退出代码而不是错误。这也允许单元测试直接验证此行为。

1
2
3
4
5
6
7

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:

​ 更一般地说，请注意，这些示例中使用的 run() 函数并非旨在具有规定性。在 run() 函数的名称、签名和设置中存在灵活性。除其他事项外，您可能：

• accept unparsed command line arguments (e.g., run(os.Args[1:])) 接受未解析的命令行参数（例如， run(os.Args[1:]) ）
• parse command line arguments in main() and pass them onto run 在 main() 中解析命令行参数并将其传递给 run
• use a custom error type to carry the exit code back to main() 使用自定义错误类型将退出代码传回 main()
• put business logic in a different layer of abstraction from package main 将业务逻辑放在与 package main 不同的抽象层中

This guidance only requires that there’s a single place in your main() responsible for actually exiting the process.

​ 此指南仅要求在您的 main() 中有一个负责实际退出进程的位置。

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.

​ 任何编组到 JSON、YAML 或其他支持基于标记的字段命名的格式的结构字段都应使用相关标记进行注释。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

// Bad
type Stock struct {
  Price int
  Name  string
}

bytes, err := json.Marshal(Stock{
  Price: 137,
  Name:  "UBER",
})
// Good
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",
})

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.

​ 基本原理：结构的序列化形式是不同系统之间的契约。对序列化形式的结构（包括字段名称）进行更改会破坏此契约。在标记内指定字段名称使契约显式化，并且它可以防止通过重构或重命名字段来意外破坏契约。

Don’t fire-and-forget goroutines 不要使用即用即弃的 goroutine

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.

​ Goroutine 很轻量，但它们不是免费的：至少，它们需要内存来存储它们的堆栈和 CPU 来进行调度。虽然对于 Goroutine 的典型用途来说这些成本很小，但当大量生成 Goroutine 且没有受控的生命周期时，它们可能会导致严重的性能问题。具有不受管理的生命周期的 Goroutine 还会导致其他问题，例如阻止未使用的对象被垃圾回收，以及持有不再使用的资源。

Therefore, do not leak goroutines in production code. Use go.uber.org/goleak to test for goroutine leaks inside packages that may spawn goroutines.

​ 因此，不要在生产代码中泄漏 Goroutine。使用 go.uber.org/goleak 来测试可能生成 Goroutine 的包中的 Goroutine 泄漏。

In general, every goroutine:

​ 通常，每个 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 必须有一种方法向 Goroutine 发出信号，指示它应该停止

In both cases, there must be a way code to block and wait for the goroutine to finish.

​ 在这两种情况下，都必须有一种方法来阻塞代码并等待 Goroutine 完成。

For example:

​ 例如：

1
2
3
4
5
6
7

// Bad
go func() {
  for {
    flush()
    time.Sleep(delay)
  }
}()

There’s no way to stop this goroutine. This will run until the application exits.

​ 没有办法停止此 Goroutine。这将一直运行，直到应用程序退出。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// Good
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

This goroutine can be stopped with close(stop), and we can wait for it to exit with <-done.

​ 可以使用 close(stop) 停止此 Goroutine，我们可以使用 <-done 等待它退出。

Wait for goroutines to exit 等待 Goroutine 退出

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

  ​ 使用 sync.WaitGroup 。如果要等待多个协程，请执行此操作

  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.

  ​ 添加另一个 chan struct{} ，协程完成后将其关闭。如果只有一个协程，请执行此操作。

  done := make(chan struct{})
  go func() {
    defer close(done)
    // ...
  }()
  
  // To wait for the goroutine to finish:
  <-done
  

No goroutines in init() init() 中没有协程

init() functions should not spawn goroutines. See also Avoid init().

​ init() 函数不应生成协程。另请参阅避免使用 init()。

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.

​ 如果某个包需要后台协程，则它必须公开一个负责管理协程生命周期的对象。该对象必须提供一个方法（ Close 、 Stop 、 Shutdown 等）来指示后台协程停止，并等待其退出。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Bad
func init() {
  go doWork()
}

func doWork() {
  for {
    // ...
  }
}

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.

​ 当用户导出此包时，无条件生成后台协程。用户无法控制协程或停止协程的方法。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// Good
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
}

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 WaitGroups if the worker manages multiple goroutines. See Wait for goroutines to exit.

​ 请注意，如果工作进程管理多个协程，则应使用 WaitGroup 。请参阅等待协程退出。

Performance 性能

Performance-specific guidelines apply only to the hot path.

​ 性能特定准则仅适用于热路径。

Prefer strconv over fmt 优先使用 strconv 而非 fmt

When converting primitives to/from strings, strconv is faster than fmt.

​ 将基本类型转换为字符串或从字符串转换基本类型时， strconv 比 fmt 更快。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

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

// BenchmarkFmtSprint-4    143 ns/op    2 allocs/op
// Good
for i := 0; i < b.N; i++ {
  s := strconv.Itoa(rand.Int())
}

// BenchmarkStrconv-4    64.2 ns/op    1 allocs/op

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.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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

// BenchmarkBad-4   50000000   22.2 ns/op
// Good
data := []byte("Hello world")
for i := 0; i < b.N; i++ {
  w.Write(data)
}

// BenchmarkGood-4  500000000   3.25 ns/op

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().

​ 尽可能在使用 make() 初始化映射时提供容量提示。

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.

​ 向 make() 提供容量提示会尝试在初始化时调整映射大小，从而减少随着元素添加到映射中而需要增加映射和分配的情况。

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.

​ 请注意，与切片不同，映射容量提示不保证完全的抢占式分配，但用于估算所需的哈希映射存储桶数。因此，即使达到指定容量，在向映射中添加元素时仍可能发生分配。

1
2
3
4
5
6
7

// Bad
m := make(map[string]os.FileInfo)

files, _ := os.ReadDir("./files")
for _, f := range files {
    m[f.Name()] = f
}

m is created without a size hint; there may be more allocations at assignment time.

​ m 在没有大小提示的情况下创建；在分配时可能会有更多分配。

1
2
3
4
5
6
7
8

// Good

files, _ := os.ReadDir("./files")

m := make(map[string]os.DirEntry, len(files))
for _, f := range files {
    m[f.Name()] = f
}

m is created with a size hint; there may be fewer allocations at assignment time.

​ m 在具有大小提示的情况下创建；在分配时可能会有更少的分配。

Specifying Slice Capacity 指定切片容量

Where possible, provide capacity hints when initializing slices with make(), particularly when appending.

​ 在可能的情况下，在使用 make() 初始化切片时提供容量提示，尤其是在追加时。

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).

​ 与映射不同，切片容量不是提示：编译器将为 make() 提供的切片容量分配足够的内存，这意味着后续 append() 操作将产生零个分配（直到切片长度与容量匹配，之后任何追加都需要调整大小以容纳其他元素）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// Bad
for n := 0; n < b.N; n++ {
  data := make([]int, 0)
  for k := 0; k < size; k++{
    data = append(data, k)
  }
}

// BenchmarkBad-4    100000000    2.48s
// Good
for n := 0; n < b.N; n++ {
  data := make([]int, 0, size)
  for k := 0; k < size; k++{
    data = append(data, k)
  }
}

// BenchmarkGood-4   100000000    0.21s

Style 样式

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.

​ 我们建议将软行长度限制为 99 个字符。作者应在达到此限制之前换行，但这不是硬性限制。代码可以超过此限制。

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.

​ 将这些准则应用于代码库时，建议在包（或更大）级别进行更改：在子包级别进行应用会违反上述关注点，因为会在同一代码中引入多种样式。

Group Similar Declarations 对类似声明进行分组

Go supports grouping similar declarations.

​ Go 支持对类似声明进行分组。

1
2
3
4
5
6
7
8

// Bad
import "a"
import "b"
// Good
import (
  "a"
  "b"
)

This also applies to constants, variables, and type declarations.

​ 这也适用于常量、变量和类型声明。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// Bad

const a = 1
const b = 2



var a = 1
var b = 2



type Area float64
type Volume float64
// Good
const (
  a = 1
  b = 2
)

var (
  a = 1
  b = 2
)

type (
  Area float64
  Volume float64
)

Only group related declarations. Do not group declarations that are unrelated.

​ 仅对相关的声明进行分组。不要对不相关的声明进行分组。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

// Bad
type Operation int

const (
  Add Operation = iota + 1
  Subtract
  Multiply
  EnvVar = "MY_ENV"
)
// Good
type Operation int

const (
  Add Operation = iota + 1
  Subtract
  Multiply
)

const EnvVar = "MY_ENV"

Groups are not limited in where they can be used. For example, you can use them inside of functions.

​ 组的使用位置不受限制。例如，您可以在函数内部使用它们。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18