uber go 编码规范

内容列表

指导原则
- 指向interface的指针
- 接收器(receiver)与接口
- 零值Mutex是有效的
- 在边界处拷贝Slices和Mapsies
- 使用defer做清理
- Channel的size要么是1要么是无缓冲的
- 枚举从1开始
- 错误类型
- 错误包装
- 处理类型断言失败
- 不要Panic
- 避免可变全局变量
性能
- strconv性能优于fmt
- 避免string到byte的转换
- 最好指定Map容量大小
代码风格
- 保持一致
- 相似的声明放在一组
- Import组内的包导入顺序
- 包名
- 函数名
- 导入别名
- 函数分组与顺序
- 减少嵌套
- 不必要的else
- 顶层变量声明
- 结构体中的嵌入
- 使用字段名初始化结构体
- 本地变量声明
- nil是一个有效的slice
- 缩小变量作用域
- 避免裸参数
- 使用原始字符串字面值，避免转义
- 初始化结构体引用
- 初始化Maps
- 格式化字符串放在Printf外部
- 为Printf样式函数命名
模式
- 测试表
- 功能选项

指导原则

指向interface的指针

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

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

一个包含type信息的指针。
数据指针。如果存储的数据是指针，则直接存储。如果存储的数据是一个值，则存储指向该值的指针。

如果要接口方法修改底层数据，则必须用指向目标对象的指针赋值给接口类型变量

接收器与接口

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

例如,

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

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

Good

var mu sync.Mutex
mu.Lock()

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

type smap struct {
  sync.Mutex // 仅针对非导出类型

  data map[string]string
}

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

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

  return m.data[k]
}

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

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

Go语言中所有的传参都是值传递（传值），都是一个副本，一个拷贝。因为拷贝的内容有时候是非引用类型（int、string、struct等这些），这样就在函数中就无法修改原内容数据；有的是引用类型（指针、map、slice、chan等这些），这样就可以修改原内容数据。

需要特别注意！当map或slice作为函数参数传入时，如果你不小心保留了对它们的引用，则用户可以对其进行修改。

Bad

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

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

// 是要修改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)

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

slice 和 map 作为返回值

当我们的函数返回 slice 或者 map 的时候，也要注意是不是直接返回了内部数据的引用到外部。

Bad

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的访问将会受到数据竞争的影响
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现在是一个拷贝
snapshot := stats.Snapshot()

使用defer做清理

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

Bad

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

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

return newCount

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

Good

p.Lock()
defer p.Unlock()

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

p.count++
return p.count

// 可读性更高

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

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

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

Bad

// 对任何人来说都应该够了！
c := make(chan int, 64)

Good

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

枚举从1开始

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

Bad

type Operation int

const (
  Add Operation = iota
  Subtrac
  Multiply
)

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

Good

type Operation int

const (
  Add Operation = iota + 1
  Subtract
  Multiply
)

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

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

type LogOutput int

const (
  LogToStdout LogOutput = iota
  LogToFile
  LogToRemote
)

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

错误类型

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

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

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

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

如果客户需要检测错误，并且是通过errors.New创建的一个简单的错误，请使用var 声明这个错误类型。

Bad

// package foo

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

// package bar

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

Good

// package foo

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

func Open() error {
  return ErrCouldNotOpen
}

// package bar

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

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

Bad

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

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

Good

type errNotFound struct {
  file string
}

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

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

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

直接导出自定义错误类型时要小心，因为这意味着他们已经成为包的公开API的一部分了。更好的方式是暴露一个匹配函数来检测错误。

// package foo

type errNotFound struct {
  file string
}

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

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

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

// package bar

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

错误包装

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

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

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

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

Bad

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

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

Good

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

x: y: new store: the error

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

参见 Don't just check errors, handle them gracefully.

处理类型断言失败

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

Bad

t := i.(string)

Good

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

不要Panic

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

Bad

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

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

Good

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

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

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

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

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

Bad

// func TestFoo(t *testing.T)

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

Good

// func TestFoo(t *testing.T)

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

避免可变全局变量

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

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

性能

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

strconv性能优于fmt

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

Bad

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

BenchmarkFmtSprint-4    143 ns/op    2 allocs/op

Good

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

BenchmarkStrconv-4    64.2 ns/op    1 allocs/op

避免string到byte的转换

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

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

最好指定Map容量大小

如果可以，在用 make()初始化map时给定Map容量大小暗示。

make(map[T1]T2, hint)

为make() 添加一定的容量提示一定程度上会减少map底层添加元素时的内存不断分配的消耗。

Bad

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

files, _ := ioutil.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.

Good


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

m := make(map[string]os.FileInfo, 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.

代码风格

保持一致

本文件中概述的一些准则可以客观评估；
其他的是情景的、上下文的或主观的。

最重要的是, 保持一致.

一致的代码更容易维护，更容易合理化，需要的更少认知开销，并且随着新的约定的出现更容易迁移、更新或者修复同一类错误。

相反，在一个单一的代码库会出现多种不同或冲突的风格的代码风格，会导致维护开销、不确定性和认知失调，所有这些都会直接导致开发速度地下、代码审查异常痛苦，当然还有BUG。

将这些准则应用于代码库时，建议更改在包级别(或更高的)层级生成.

相似的声明放在一组

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

Bad

import "a"
import "b"

Good

import (
  "a"
  "b"
)

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

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
)

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

Bad

type Operation int

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

Good

type Operation int

const (
  Add Operation = iota + 1
  Subtract
  Multiply
)

const ENV_VAR = "MY_ENV"

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

Bad

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

  ...
}

Good

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

  ...
}

Import组内的包导入顺序

应该有两类导入组：

标准库
其他

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

Bad

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

Good

import (
  "fmt"
  "os"

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

包名

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

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

另请参阅[包名规范] 和 [Go包样式指南].

函数名

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

导入别名

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

import (
  "net/http"

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

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

Bad

import (
  "fmt"
  "os"


  nettrace "golang.net/x/trace"
)

Good

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

  nettrace "golang.net/x/trace"
)

函数分组与顺序

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

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

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

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

Bad

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

type something struct{ ... }

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

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

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

Good

type something struct{ ... }

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

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

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

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

减少嵌套

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

看下面的示例，优先判断错误，有错误尽快continue进行循环。正常的无需判断err的逻辑放在最后。

Bad

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

Good

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

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

不必要的else

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

Bad

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

Good

a := 10
if b {
  a = 100
}

顶层变量声明

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

Bad

var _s string = F()

func F() string { return "A" }

Good

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

func F() string { return "A" }

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

type myError struct{}

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

func F() myError { return myError{} }

var _e error = F()
// F returns an object of type myError but we want error.

结构体中的嵌入

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

Bad

type Client struct {
  version int
  http.Client
}

Good

type Client struct {
  http.Client

  version int
}

使用字段名初始化结构体

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

Bad

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

Good

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

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

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

本地变量声明

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

Bad

var s = "foo"

Good

s := "foo"

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

Bad

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

Good

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

nil是一个有效的slice

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

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

Bad

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

Good

if x == "" {
  return nil
}

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

Bad

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

Good

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

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

Bad

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

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

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

Good

var nums []int

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

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

缩小变量作用域

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

Bad

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

Good

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

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

Bad

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

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

Good

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

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

fmt.Println(cfg)
return nil

避免裸参数

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

Bad

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

printInfo("foo", true, true)

Good

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

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

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

type Region int

const (
  UnknownRegion Region = iota
  Local
)

type Status int

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

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

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

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

Bad

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

Good

wantError := `unknown error:"test"`

初始化结构体引用

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

Bad

sval := T{Name: "foo"}

// inconsistent
sptr := new(T)
sptr.Name = "bar"

Good

sval := T{Name: "foo"}

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

初始化Maps

用 make(..) 创建空的Maps,用程序填充Maps。
这中写法使得map初始化和声明看起来是不同的，如果需要，以后可以很容易地为map添加大小提示。

Bad

var (
  // m1 is safe to read and write;
  // m2 will panic on writes.
  m1 = map[T1]T2{}
  m2 map[T1]T2
)

声明和初始化看起来是相似的。
Good

var (
  // m1 is safe to read and write;
  // m2 will panic on writes.
  m1 = make(map[T1]T2)
  m2 map[T1]T2
)

声明和初始化看起来是不同的。

在可能的情况下，在使用make()初始化时给定容量提示。具体内容见：最好指定Map容量大小

另一方面，如果map包含固定的元素列表，使用map文本初始化map。

Bad

m := make(map[T1]T2, 3)
m[k1] = v1
m[k2] = v2
m[k3] = v3

Good

m := map[T1]T2{
  k1: v1,
  k2: v2,
  k3: v3,
}

基本的经验法则是在添加一组固定的元素，否则使用make（并指定大小提示，如果有的话）。

格式化字符串放在Printf外部

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

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

Bad

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

Good

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

为Printf样式函数命名

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

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

如果不能使用预定义的名称，请以 f 结尾：Wrapf，而非 Wrap。因为 go vet 可以指定检查特定的 Printf 样式名称，但名称必须以 f 结尾。

$ go vet -printfuncs=wrapf,statusf

另见 go vet: Printf family check.

模式

测试表

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

Bad

// func TestSplitHostPort(t *testing.T)

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

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

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

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

Good

// func TestSplitHostPort(t *testing.T)

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

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

测试表在错误消息处理上，包括注入上下文信息、减少重复的逻辑、添加新的测试用例，都变得更加容易。

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

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

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

功能选项

功能选项是一种模式，声明一个不透明Option类型，该类型记录某些内部结构体的信息。您的函数接受这些不定数量的选项参数，并将选项参数上的信息作用于内部结构上。

此模式可用于扩展构造函数和实现其他公共 API 中的可选参数，特别是这些参数已经有三个或者超过三个的情况下。

Bad

// package db

func Open(
  addr string,
  cache bool,
  logger *zap.Logger
) (*Connection, error) {
  // ...
}

必须始终提供cache和logger参数，即使用户希望使用默认值。

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)

Good

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

Options 仅在需要时提供

db.Open(addr)
db.Open(addr, db.WithLogger(log))
db.Open(addr, db.WithCache(false))
db.Open(
  addr,
  db.WithCache(false),
  db.WithLogger(log),
)

我们建议的实现此模式的方法是使用Option接口,

保存不可导出的方法，在不可导出的Option上记录选项结构。

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允许用"用户可读的字符串"表示option。

另见,

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

uber go 编码规范

内容列表

指导原则

指向interface的指针

接收器与接口

零值Mutex是有效的

在边界处拷贝Slices和Maps

接收Slices和Maps

slice 和 map 作为返回值

使用defer做清理

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

枚举从1开始

错误类型

错误包装

处理类型断言失败

不要Panic

避免可变全局变量

性能

strconv性能优于fmt

避免string到byte的转换

最好指定Map容量大小

代码风格

保持一致

相似的声明放在一组

Import组内的包导入顺序

包名

函数名

导入别名

函数分组与顺序

减少嵌套

不必要的else

顶层变量声明

结构体中的嵌入

使用字段名初始化结构体

本地变量声明

nil是一个有效的slice

缩小变量作用域

避免裸参数

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

初始化结构体引用

初始化Maps

格式化字符串放在Printf外部

为Printf样式函数命名

模式

测试表

功能选项

你可能感兴趣的:(uber go 编码规范)