Uber Go 语言编码规范

时间 2019-11-16

标签 uber 语言编码规范栏目硅谷繁體版

原文原文链接

Uber Go 语言编码规范

Uber 是一家美国硅谷的科技公司，也是 Go 语言的早期 adopter。其开源了不少 golang 项目，诸如被 Gopher 圈熟知的 zap、jaeger 等。2018 年年底 Uber 将内部的 Go 风格规范开源到 GitHub，通过一年的积累和更新，该规范已经初具规模，并受到广大 Gopher 的关注。本文是该规范的中文版本。本版本会根据原版实时更新。html

## 版本git

当前更新版本：2019-11-13 版本地址：commit:#71
若是您发现任何更新、问题或改进，请随时 fork 和 PR
Please feel free to fork and PR if you find any updates, issues or improvement.

介绍

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

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

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

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

全部代码都应该经过golint和go vet的检查并没有错误。咱们建议您将编辑器设置为：c#

保存时运行 goimports
运行 golint 和 go vet 检查错误

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

指导原则

指向 interface 的指针

您几乎不须要指向接口类型的指针。您应该将接口做为值进行传递，在这样的传递过程当中，实质上传递的底层数据仍然能够是指针。安全

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

一个指向某些特定类型信息的指针。您能够将其视为"type"。
数据指针。若是存储的数据是指针，则直接存储。若是存储的数据是一个值，则存储指向该值的指针。

若是但愿接口方法修改基础数据，则必须使用指针传递。

接收器 (receiver) 与接口

使用值接收器的方法既能够经过值调用，也能够经过指针调用。

例如，

type S struct {
  data string
}

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

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

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

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

// 这不能编译经过：
//  sVals[1].Write("test")

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

// 经过指针既能够调用 Read，也能够调用 Write 方法
sPtrs[1].Read()
sPtrs[1].Write("test")

一样，即便该方法具备值接收器，也能够经过指针来知足接口。

type F interface {
  f()
}

type S1 struct{}

func (s S1) f() {}

type S2 struct{}

func (s *S2) f() {}

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

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

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

Effective Go 中有一段关于 pointers vs. values 的精彩讲解。

零值 Mutex 是有效的

零值 sync.Mutex 和 sync.RWMutex 是有效的。因此指向 mutex 的指针基本是没必要要的。

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

若是你使用结构体指针，mutex 能够非指针形式做为结构体的组成字段，或者更好的方式是直接嵌入到结构体中。
若是是私有结构体类型或是要实现 Mutex 接口的类型，咱们可使用嵌入 mutex 的方法：

```go type smap struct { sync.Mutex // only for unexported types（仅适用于非导出类型） 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] } ```	```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] } ```
为私有类型或须要实现互斥接口的类型嵌入。	对于导出的类型，请使用专用字段。

在边界处拷贝 Slices 和 Maps

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

接收 Slices 和 Maps

请记住，当 map 或 slice 做为函数参数传入时，若是您存储了对它们的引用，则用户能够对其进行修改。

Bad	Good
```go func (d *Driver) SetTrips(trips []Trip) { d.trips = trips } trips := ... d1.SetTrips(trips) // 你是要修改 d1.trips 吗？ trips[0] = ... ```	```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] = ... ```

返回 slices 或 maps

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

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

使用 defer 释放资源

使用 defer 释放资源，诸如文件和锁。

Bad	Good
```go p.Lock() if p.count < 10 { p.Unlock() return p.count } p.count++ newCount := p.count p.Unlock() return newCount // 当有多个 return 分支时，很容易遗忘 unlock ```	```go p.Lock() defer p.Unlock() if p.count < 10 { return p.count } p.count++ return p.count // 更可读 ```

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

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

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

Bad	Good
```go // 应该足以知足任何状况！ c := make(chan int, 64) ```	```go // 大小：1 c := make(chan int, 1) // 或者 // 无缓冲 channel，大小为 0 c := make(chan int) ```

枚举从 1 开始

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

Bad	Good
```go type Operation int const ( Add Operation = iota Subtract Multiply ) // Add=0, Subtract=1, Multiply=2 ```	```go type Operation int const ( Add Operation = iota + 1 Subtract Multiply ) // Add=1, Subtract=2, Multiply=3 ```

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

type LogOutput int

const (
  LogToStdout LogOutput = iota
  LogToFile
  LogToRemote
)

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

错误类型

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

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

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

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

若是客户端须要检测错误，而且您已使用建立了一个简单的错误 errors.New，请使用一个错误变量。

Bad	Good
```go // package foo func Open() error { return errors.New("could not open") } // package bar func use() { if err := foo.Open(); err != nil { if err.Error() == "could not open" { // handle } else { panic("unknown error") } } } ```	```go // package foo var ErrCouldNotOpen = errors.New("could not open") func Open() error { return ErrCouldNotOpen } // package bar if err := foo.Open(); err != nil { if err == foo.ErrCouldNotOpen { // handle } else { panic("unknown error") } } ```

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

Bad	Good
```go func open(file string) error { return fmt.Errorf("file %q not found", file) } func use() { if err := open(); err != nil { if strings.Contains(err.Error(), "not found") { // handle } else { panic("unknown error") } } } ```	```go type errNotFound struct { file string } func (e errNotFound) Error() string { return fmt.Sprintf("file %q not found", e.file) } func open(file string) error { return errNotFound{file: file} } func use() { if err := open(); err != nil { if _, ok := err.(errNotFound); ok { // handle } else { panic("unknown error") } } } ```

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

// package foo

type errNotFound struct {
  file string
}

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

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

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

// package bar

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

错误包装 (Error Wrapping)

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

若是没有要添加的其余上下文，而且您想要维护原始错误类型，则返回原始错误。
添加上下文，使用 "pkg/errors".Wrap 以便错误消息提供更多上下文 ,"pkg/errors".Cause 可用于提取原始错误。
Use fmt.Errorf if the callers do not need to detect or handle that specific error case.
若是调用者不须要检测或处理的特定错误状况，使用 fmt.Errorf。

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

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

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

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

另请参见 Don't just check errors, handle them gracefully. 不要只是检查错误，要优雅地处理错误

处理类型断言失败

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

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

不要 panic

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

Bad	Good
```go func foo(bar string) { if len(bar) == 0 { panic("bar must not be empty") } // ... } func main() { if len(os.Args) != 2 { fmt.Println("USAGE: foo ") os.Exit(1) } foo(os.Args[1]) } ```	```go func foo(bar string) error { if len(bar) == 0 { return errors.New("bar must not be empty") } // ... return nil } func main() { if len(os.Args) != 2 { fmt.Println("USAGE: foo ") os.Exit(1) } if err := foo(os.Args[1]); err != nil { panic(err) } } ```

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

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

即便在测试代码中，也优先使用t.Fatal或者t.FailNow而不是 panic 来确保失败被标记。

Bad	Good
```go // func TestFoo(t *testing.T) f, err := ioutil.TempFile("", "test") if err != nil { panic("failed to set up test") } ```	```go // func TestFoo(t *testing.T) f, err := ioutil.TempFile("", "test") if err != nil { t.Fatal("failed to set up test") } ```

使用 go.uber.org/atomic

使用 sync/atomic 包的原子操做对原始类型 (int32, int64等）进行操做，由于很容易忘记使用原子操做来读取或修改变量。

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

Bad	Good
```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! } ```	```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() } ```

性能

性能方面的特定准则只适用于高频场景。

优先使用 strconv 而不是 fmt

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

Bad	Good
```go for i := 0; i < b.N; i++ { s := fmt.Sprint(rand.Int()) } ```	```go for i := 0; i < b.N; i++ { s := strconv.Itoa(rand.Int()) } ```
``` BenchmarkFmtSprint-4 143 ns/op 2 allocs/op ```	``` BenchmarkStrconv-4 64.2 ns/op 1 allocs/op ```

避免字符串到字节的转换

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

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

尽可能初始化时指定 Map 容量

在尽量的状况下，在使用 make() 初始化的时候提供容量信息

make(map[T1]T2, hint)

为 make() 提供容量信息（hint）尝试在初始化时调整 map 大小，
这减小了在将元素添加到 map 时增加和分配的开销。
注意，map 不能保证分配 hint 个容量。所以，即便提供了容量，添加元素仍然能够进行分配。

Bad	Good
```go m := make(map[string]os.FileInfo) files, _ := ioutil.ReadDir("./files") for _, f := range files { m[f.Name()] = f } ```	```go files, _ := ioutil.ReadDir("./files") m := make(map[string]os.FileInfo, len(files)) for _, f := range files { m[f.Name()] = f } ```
`m` 是在没有大小提示的状况下建立的；在运行时可能会有更多分配。	`m` 是有大小提示建立的；在运行时可能会有更少的分配。

规范

一致性

本文中概述的一些标准都是客观性的评估，是根据场景、上下文、或者主观性的判断；

可是最重要的是，保持一致.

一致性的代码更容易维护、是更合理的、须要更少的学习成本、而且随着新的约定出现或者出现错误后更容易迁移、更新、修复 bug

相反，一个单一的代码库会致使维护成本开销、不肯定性和认知误差。全部这些都会直接致使速度下降、
代码审查痛苦、并且增长 bug 数量

将这些标准应用于代码库时，建议在 package（或更大）级别进行更改，子包级别的应用程序经过将多个样式引入到同一代码中，违反了上述关注点。

类似的声明放在一组

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

Bad	Good
```go import "a" import "b" ```	```go import ( "a" "b" ) ```

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

Bad	Good
```go const a = 1 const b = 2 var a = 1 var b = 2 type Area float64 type Volume float64 ```	```go const ( a = 1 b = 2 ) var ( a = 1 b = 2 ) type ( Area float64 Volume float64 ) ```

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

Bad	Good
```go type Operation int const ( Add Operation = iota + 1 Subtract Multiply ENV_VAR = "MY_ENV" ) ```	```go type Operation int const ( Add Operation = iota + 1 Subtract Multiply ) const ENV_VAR = "MY_ENV" ```

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

Bad	Good
```go func f() string { var red = color.New(0xff0000) var green = color.New(0x00ff00) var blue = color.New(0x0000ff) ... } ```	```go func f() string { var ( red = color.New(0xff0000) green = color.New(0x00ff00) blue = color.New(0x0000ff) ) ... } ```

import 分组

导入应该分为两组：

标准库
其余库

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

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

包名

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

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

另请参阅 Package Names 和 Go 包样式指南.

函数名

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

导入别名

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

import (
  "net/http"

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

在全部其余状况下，除非导入之间有直接冲突，不然应避免导入别名。

Bad	Good
```go import ( "fmt" "os" nettrace "golang.net/x/trace" ) ```	```go import ( "fmt" "os" "runtime/trace" nettrace "golang.net/x/trace" ) ```

函数分组与顺序

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

所以，导出的函数应先出如今文件中，放在struct, const, var定义的后面。

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

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

Bad	Good
```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{} } ```	```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 {...} ```

减小嵌套

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

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

没必要要的 else

若是在 if 的两个分支中都设置了变量，则能够将其替换为单个 if。

Bad	Good
```go var a int if b { a = 100 } else { a = 10 } ```	```go a := 10 if b { a = 100 } ```

顶层变量声明

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

Bad	Good
```go var _s string = F() func F() string { return "A" } ```	```go var _s = F() // 因为 F 已经明确了返回一个字符串类型，所以咱们没有必要显式指定_s 的类型 // 仍是那种类型 func F() string { return "A" } ```

若是表达式的类型与所需的类型不彻底匹配，请指定类型。

type myError struct{}

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

func F() myError { return myError{} }

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

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

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

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

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

Bad	Good
```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. } ```	```go // foo.go const ( _defaultPort = 8080 _defaultUser = "user" ) ```

结构体中的嵌入

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

Bad	Good
```go type Client struct { version int http.Client } ```	```go type Client struct { http.Client version int } ```

使用字段名初始化结构体

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

Bad	Good
```go k := User{"John", "Doe", true} ```	```go k := User{ FirstName: "John", LastName: "Doe", Admin: true, } ```

例外：若是有 3 个或更少的字段，则能够在测试表中省略字段名称。

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

本地变量声明

若是将变量明确设置为某个值，则应使用短变量声明形式 (:=)。

Bad	Good
```go var s = "foo" ```	```go s := "foo" ```

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

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

nil 是一个有效的 slice

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

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

Bad Good

```go if x == "" { return []int{} } ``` ```go if x == "" { return nil } ```

Bad	Good
```go if x == "" { return []int{} } ```	```go if x == "" { return nil } ```

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

Bad	Good
```go func isEmpty(s []string) bool { return s == nil } ```	```go func isEmpty(s []string) bool { return len(s) == 0 } ```

零值切片（用var声明的切片）可当即使用，无需调用make()建立。

Bad	Good
```go nums := []int{} // or, nums := make([]int) if add1 { nums = append(nums, 1) } if add2 { nums = append(nums, 2) } ```	```go var nums []int if add1 { nums = append(nums, 1) } if add2 { nums = append(nums, 2) } ```

小变量做用域

若是有可能，尽可能缩小变量做用范围。除非它与减小嵌套的规则冲突。

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

若是须要在 if 以外使用函数调用的结果，则不该尝试缩小范围。

Bad	Good
```go if data, err := ioutil.ReadFile(name); err == nil { err = cfg.Decode(data) if err != nil { return err } fmt.Println(cfg) return nil } else { return err } ```	```go data, err := ioutil.ReadFile(name) if err != nil { return err } if err := cfg.Decode(data); err != nil { return err } fmt.Println(cfg) return nil ```

避免参数语义不明确(Avoid Naked Parameters)

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

Bad	Good
```go // func printInfo(name string, isLocal, done bool) printInfo("foo", true, true) ```	```go // func printInfo(name string, isLocal, done bool) printInfo("foo", true /* isLocal /, true / done */) ```

对于上面的示例代码，还有一种更好的处理方式是将上面的 bool 类型换成自定义类型。未来，该参数能够支持不只仅局限于两个状态（true/false）。

type Region int

const (
  UnknownRegion Region = iota
  Local
)

type Status int

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

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

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

Go 支持使用原始字符串字面值，也就是 " ` " 来表示原生字符串，在须要转义的场景下，咱们应该尽可能使用这种方案来替换。

能够跨越多行并包含引号。使用这些字符串能够避免更难阅读的手工转义的字符串。

Bad	Good
```go wantError := "unknown name:\"test\"" ```	```go wantError := `unknown error:"test"` ```

初始化 Struct 引用

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

Bad	Good
```go sval := T{Name: "foo"} // inconsistent sptr := new(T) sptr.Name = "bar" ```	```go sval := T{Name: "foo"} sptr := &T{Name: "bar"} ```

初始化 Maps

对于空 map 请使用 make(..) 初始化，而且 map 是经过编程方式填充的。
这使得 map 初始化在表现上不一样于声明，而且它还能够方便地在 make 后添加大小提示。

Bad	Good
```go var ( // m1 读写安全; // m2 在写入时会 panic m1 = map[T1]T2{} m2 map[T1]T2 ) ```	```go var ( // m1 读写安全; // m2 在写入时会 panic m1 = make(map[T1]T2) m2 map[T1]T2 ) ```
声明和初始化看起来很是类似的。	声明和初始化看起来差异很是大。

在尽量的状况下，请在初始化时提供 map 容量大小，详细请看尽可能初始化时指定 Map 容量。

另外，若是 map 包含固定的元素列表，则使用 map literals(map 初始化列表) 初始化映射。

Bad	Good
```go m := make(map[T1]T2, 3) m[k1] = v1 m[k2] = v2 m[k3] = v3 ```	```go m := map[T1]T2{ k1: v1, k2: v2, k3: v3, } ```

基本准则是：在初始化时使用 map 初始化列表来添加一组固定的元素。不然使用 make (若是能够，请尽可能指定 map 容量)。

字符串 string format

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

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

Bad	Good
```go msg := "unexpected values %v, %v\n" fmt.Printf(msg, 1, 2) ```	```go const msg = "unexpected values %v, %v\n" fmt.Printf(msg, 1, 2) ```

命名 Printf 样式的函数

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

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

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

$ go vet -printfuncs=wrapf,statusf

另请参阅 go vet: Printf family check.

编程模式

表驱动测试

当测试逻辑是重复的时候，经过 subtests 使用 table 驱动的方式编写 case 代码看上去会更简洁。

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

Bad

Good

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

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

很明显，使用 test table 的方式在代码逻辑扩展的时候，好比新增 test case，都会显得更加的清晰。

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

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

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

功能选项

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

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

Bad	Good
```go // package db func Connect( addr string, timeout time.Duration, caching bool, ) (Connection, error) { // ... } // Timeout and caching must always be provided, // even if the user wants to use the default. db.Connect(addr, db.DefaultTimeout, db.DefaultCaching) db.Connect(addr, newTimeout, db.DefaultCaching) db.Connect(addr, db.DefaultTimeout, false / caching /) db.Connect(addr, newTimeout, false / caching */) ```	```go type options struct { timeout time.Duration caching bool } // Option overrides behavior of Connect. type Option interface { apply(options) } type optionFunc func(options) func (f optionFunc) apply(o options) { f(o) } func WithTimeout(t time.Duration) Option { return optionFunc(func(o options) { o.timeout = t }) } func WithCaching(cache bool) Option { return optionFunc(func(o options) { o.caching = cache }) } // Connect creates a connection. func Connect( addr string, opts ...Option, ) (Connection, error) { options := options{ timeout: defaultTimeout, caching: defaultCaching, } for _, o := range opts { o.apply(&options) } // ... } // Options must be provided only if needed. db.Connect(addr) db.Connect(addr, db.WithTimeout(newTimeout)) db.Connect(addr, db.WithCaching(false)) db.Connect( addr, db.WithCaching(false), db.WithTimeout(newTimeout), ) ```

Bad

Good

```go // package db func Connect( addr string, timeout time.Duration, caching bool, ) (*Connection, error) { // ... } // Timeout and caching must always be provided, // even if the user wants to use the default. db.Connect(addr, db.DefaultTimeout, db.DefaultCaching) db.Connect(addr, newTimeout, db.DefaultCaching) db.Connect(addr, db.DefaultTimeout, false /* caching */) db.Connect(addr, newTimeout, false /* caching */) ```

```go type options struct { timeout time.Duration caching bool } // Option overrides behavior of Connect. type Option interface { apply(*options) } type optionFunc func(*options) func (f optionFunc) apply(o *options) { f(o) } func WithTimeout(t time.Duration) Option { return optionFunc(func(o *options) { o.timeout = t }) } func WithCaching(cache bool) Option { return optionFunc(func(o *options) { o.caching = cache }) } // Connect creates a connection. func Connect( addr string, opts ...Option, ) (*Connection, error) { options := options{ timeout: defaultTimeout, caching: defaultCaching, } for _, o := range opts { o.apply(&options) } // ... } // Options must be provided only if needed. db.Connect(addr) db.Connect(addr, db.WithTimeout(newTimeout)) db.Connect(addr, db.WithCaching(false)) db.Connect( addr, db.WithCaching(false), db.WithTimeout(newTimeout), ) ```

还能够参考下面资料：

本文由zshipu.com学习笔记或整理或转载，若有侵权请联系，必改之。

Uber Go 语言编码规范

Uber Go 语言编码规范

目录

介绍

指导原则

指向 interface 的指针

接收器 (receiver) 与接口

零值 Mutex 是有效的

在边界处拷贝 Slices 和 Maps

接收 Slices 和 Maps

返回 slices 或 maps

使用 defer 释放资源

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

枚举从 1 开始

错误类型

错误包装 (Error Wrapping)

处理类型断言失败

不要 panic

使用 go.uber.org/atomic

性能

优先使用 strconv 而不是 fmt

避免字符串到字节的转换

尽可能初始化时指定 Map 容量

规范

一致性

类似的声明放在一组

import 分组

包名

函数名

导入别名

函数分组与顺序

减小嵌套

没必要要的 else

顶层变量声明

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

结构体中的嵌入

使用字段名初始化结构体

本地变量声明

nil 是一个有效的 slice

小变量做用域

避免参数语义不明确(Avoid Naked Parameters)

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

初始化 Struct 引用

初始化 Maps

字符串 string format

命名 Printf 样式的函数

编程模式

表驱动测试

功能选项