Uber 的 Go 规范

Uber 公司推出的 Go 语言规范，建议没看过的同学看一遍，里面的规范很多，不见得每一条都采纳，不现实，选一些适合的可以落地执行的拿来参考就行。

介绍

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

本指南最初是由 Prashant Varanasi 和 Simon Newton 创建的，是为了让一些同事尽快掌握 Go 的使用方法。多年来，我们根据其他人的反馈对它进行了修改。

这记录了我们在 Uber 所遵循的 Go 代码中的习惯性约定。其中很多是 Go 里面的一般准则，而其他的则是根据外部资源进行扩展：

1. Effective Go
2. Go Common Mistakes
3. Go Code Review Comments

我们的目标是使代码样本准确地适用于 Go 的两个最新的次要版本。

所有代码在通过 golint 和 go vet 运行时应该是没有错误的。我们建议将您的编辑器设置为：

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

你可以在这里找到编辑器支持 Go 工具的信息：https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins

指南

指向 interface 的指针

你几乎不需要一个指向 interface 的指针，interface 类型数据应该直接传递，但实际上 interface 底层是一个指针。

interface 类型包括两部分：

1. 一个指向特定类型的指针。可以将其视为 “ 类型 ”。
2. 数据指针。如果底层数据是指针，会被直接存储。如果底层数据是值，那会存储这个数据的指针。

如果你想要接口方法修改基础数据，那必须使用指针。

验证接口合法性

在编译期验证接口的合法性，需要验证的有：

• 验证导出类型在作为 API 时是否实现了特定接口
• 实现一个接口的导出和非导出类型是集合的一部分
• 违反接口合理性无法编译通过，通知用户

type Handler struct { }



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

type Handler struct { }

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

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

如果 *Handler 没有实现 http.Handler 接口，那么 var _ http.Handler = (*Handler)(nil)语句在编译期就会报错；

赋值语句的右边部门应是断言类型的零值。对于指针类型(像 *Handler)、slice 和 map 类型，零值为 nil, 对于结构体类型，零值为空结构体，下面是空结构体的例子。

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


var _ http.Handler = LogHandler{}

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

接收者和接口

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

使用 指针类型 接收者的方法只能通过指针或者 addressable values 调用。

例如：

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


sVals[1].Read()




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


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

Effective Go 有一段关于 Pointers vs. Values 的优秀讲解

Mutexes 的零值是有效的

sync.Mutex 和 sync.RWMutex 的零值是有效的，所以不需要实例化一个 Mutex 的指针。

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

var mu sync.Mutex
mu.Lock()

如果结构体中包含 mutex，在使用结构体的指针时，mutex 应该是结构体的非指针字段，也不要把 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]
}

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

slice 和 map 类型包含指向 data 数据的指针，所以当你需要复制时应格外注意。

接收 Slices 和 Maps

如果在函数调用中传递 map 或 slice, 请记住这个函数可以修改它。

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

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


trips[0] = ...

func (d *Driver) SetTrips(trips []Trip) {d.trips = make([]Trip, len(trips))
  copy(d.trips, trips)
}

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


trips[0] = ...

返回 Slices 和 Maps

同样，请注意用户对 maps 或 slices 的修改暴露了内部状态。

type Stats struct {
  mu sync.Mutex
  counters map[string]int
}


func (s *Stats) Snapshot() map[string]int {s.mu.Lock()
  defer s.mu.Unlock()

  return s.counters
}


snapshot := stats.Snapshot()

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 := stats.Snapshot()

使用 Defer 释放资源

在读写文件、使用锁时，使用 defer 释放资源

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

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

return newCount

p.Lock()
defer p.Unlock()

if p.count  10 {return p.count
}

p.count++
return p.count

调用 defer 的性能开销非常小，但如果你需要纳秒级别的函数调用，那可能需要避免使用 defer。使用 defer 带来的可读性 胜过引入其它带来的性能开销。defer 尤其适用于适用于那些不仅是内存 放在的行数较多、逻辑较为复杂的大方法，这些方法中其他代码逻辑的执行成本比 defer 执行成本更大。

Channel 大小应为 0 或 1

Channels 的大小应该是 1 或无缓冲的。默认情况下，channels 是无缓冲的，size 为 0。其他 size 需经过严格的审查。考虑 channel 的 size 是如何定义的，是什么造成了 channel 在负荷情况下被写满而无法写入，以及无法写入会发生什么。

c := make(chan int, 64)

c := make(chan int, 1) 

c := make(chan int)

枚举类型值从 1 开始

在 Go 中声明枚举值的标准方法是使用 const 包 iota。由于变量的默认值为 0，因此枚举类型的值需要从 1 开始。

type Operation int

const (Add Operation = iota
  Subtract
  Multiply
)

type Operation int

const (Add Operation = iota + 1
  Subtract
  Multiply
)

当你需要将 0 值视为默认行为时，枚举类型从 0 开始是有意义的。

type LogOutput int

const (LogToStdout LogOutput = iota
  LogToFile
  LogToRemote
)

使用 time 包来处理时间

时间处理很复杂，关于时间错误预估有以下这些点。

1. 一天有 24 小时
2. 一小时有 60 分钟
3. 一周有 7 天
4. 一年有 365 天
5. 其他易错点

举例来说, 1 表示在一个时间点加上 24 小时并不一定会产生新的一天。

因此，在处理时间时应始终使用 ”time” 包，因为它会用更安全、准确的方式来处理这些不正确的假设。

用 time.Time 表示瞬时时间

需要瞬时时间语义时，使用 time.Time，在进行比较、增加或减少时间段时，使用 time.Time 包里的方法。

func isActive(now, start, stop int) bool {return start 

func isActive(now, start, stop time.Time) bool {return (start.Before(now) || start.Equal(now)) && now.Before(stop)
}

用 time.Duration 表示时间段

应使用 time.Duration 来表示时间段

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

poll(10) // 这里单位是秒还是毫秒

func poll(delay time.Duration) {// 使用 time.Duration 表示时间段
  for {// ...
    time.Sleep(delay)
  }
}

poll(10*time.Second) // 明确单位

回到刚刚的例子，在一个瞬时时间加上 24 小时，怎么加这个 “24 小时 ” 取决于我们的意图。如果我们想获取 下一天的当前时间，我们应该使用 Time.AddDate。如果我们想获取比当前时间晚 24 小时的瞬时时间，我们应该应该使用 Time.Add。

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

对外交互 使用 time.Time 和 time.Duration

在对外交互时尽可能使用 time.Duration 和 time.Time，例如：

• Command-line 标记: flag 通过支持 time.ParseDuration 来支持 time.Duration
• JSON: encoding/json 通过  [UnmarshalJSON 方法] 支持把 time.Time 解码为 RFC 3339 字符串
• SQL: database/sql 支持把 DATETIME 或 TIMESTAMP 类型转化为 time.Time
• YAML: gopkg.in/yaml.v2 支持把 time.Time 作为一个 RFC 3339 字符串, 通过支持 time.ParseDuration 来支持 time.Duration。

如果交互中不支持使用 time.Duration，那字段名中应包含单位，类型应为 int 或 float64。

例如, 由于 encoding/json 不支持 time.Duration 类型, 因此字段名中应包含时间单位。

type Config struct {Interval int `json:"interval"`
}

type Config struct {IntervalMillis int `json:"intervalMillis"`
}

如果在交互中不能使用 time.Time，除非有额外约定，否则应该使用 string 和 RFC 3339 定义的 时间戳格式。默认情况下，Time.UnmarshalText 使用这种格式，并可以通过 time.RFC3339 在 Time.Format 和 time.Parse 中使用。

尽管在实践中这不是什么问题，但是你需要记住 ”time” 不能解析闰秒时间戳(8728), 在计算中也不考虑闰秒(15190)。因此如果你要比较两个瞬时时间，比较结果不会包含这两个瞬时时间可能会出现的闰秒。

错误

错误类型

声明错误的选项很少。在为你的代码选择合适的用例之前，考虑这些事项：

• 调用方需要匹配错误吗，还是调用方需要自己处理错误。如果需要匹配错误，那应该声明顶级 错误类型或自定义类型 来让 errors.Is 或 errors.As 匹配。
• 错误信息是静态字符串吗，还是说错误信息是需要上下文的动态字符串。如果是静态字符串，我们可以使用 errors.New，如果是动态字符串，我们应该使用 fmt.Errorf 来 自定义错误类型。
• 我们是否正在传递由下游返回的新的错误类型，如果是这样，参考 section on error wrapping.

举例，使用 errors.New 表示一个静态字符串错误。如果调用方需要匹配并处理这个错误，就把这个错误声明为变量来支持和 errors.Is 匹配。

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



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

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

func Open() error {return ErrCouldNotOpen
}



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

对于动态字符串的错误，如果调用方不需要匹配就是用 fmt.Errorf，需要匹配就搞一个自定义 error。

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



if err := foo.Open("testfile.txt"); err != nil {panic("unknown error")
}

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




if err := foo.Open("testfile.txt"); err != nil {var notFound *NotFoundError
  if errors.As(err, ¬Found) {} else {panic("unknown error")
  }
}

注意，如果你的包里导出了错误变量或错误类型，那这个错误将变成你包里公共 API 的一部分。

错误包装

调用函数失败时，有三种选择供你选择：

• 返回原始错误
• 用 fmt.Errorf 和 %w 包装上下文信息
• 用 fmt.Errorf 和 %v 包装上下文信息

返回原始错误不会附加上下文信息，这样就保持了原始错误类型和信息。比较适用于 lib 库类型代码 展示底层错误信息。

如果不是 lib 库，就需要增加所需的上下文信息，不然就会出现 “connection refused” 这样非常 模糊的错误，理论上应该添加上下文，来得到这样的报错信息：”call service foo: connection refused”。

在错误类型上使用 fmt.Errorf 来添加上下文信息，根据调用方不同的使用方式，可以选择 %w 或 %v 动词。

• 如果调用方需要访问底层错误，使用 %w 动词，这是一个用来包装错误的动词，如果你在代码中使用到了它，请注意 调用方会对此产生依赖，所以当你的包装的错误是用 var 声明的已知类型，需要在你的代码里对其进行测试。
• 使用 %v 会混淆你的底层错误类型，调用方将无法进行匹配，如果有匹配需求，应该使用 %w 动词。

当为返回错误增加上下文信息时，避免在上下文中增加像 “failed to” 这样的没啥用的短语，这样没用的短语在错误 堆栈中堆积起来的话，反而不利于你定位 bug。

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

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

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

x: y: new store: the error

然而当你的错误传给别的系统时，错误信息应该足够清晰。(比如, 错误信息在日志中以 “Failed” 开头)

其他参考信息：Don’t just check errors, handle them gracefully.

错误命名

对于全局变量类型，根据是否导出使用  Err 或 err 前缀。详情参考：Prefix Unexported Globals with _.

var (ErrBrokenLink = errors.New("link is broken")
  ErrCouldNotOpen = errors.New("could not open")

  
  errNotFound = errors.New("not found")
)

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

type NotFoundError struct {File string
}

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



type resolveError struct {Path string
}

func (e *resolveError) Error() string {return fmt.Sprintf("resolve %q", e.Path)
}

todo：errors.Is 和 errors.As 的区别

处理断言失败

在不正确的类型断言上 使用单返回值来处理会导致 panic, 因此请使用 “comma ok” 习俗.

t := i.(string)

t, ok := i.(string)
if !ok { }

不要使用 Panic

在生产环境的业务代码避免使用 panic。Panics 是级联问题 cascading failures 的主要来源。如果发生错误，函数必须返回错误，让调用方决定如何处理这种情况。

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

func main() {run(os.Args[1:])
}

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 不是错误处理策略。当系统发生像空指针异常这种 不可恢复的 Fatal 异常时，才需要使用 Panic。唯一的意外情况是项目启动：如果程序启动阶段出现问题需要抛出异常。

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

即使在测试中，优先使用 t.Fatal 或 t.FailNow 而不是异常，来确保失败情况被记录。

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

f, err := os.CreateTemp("", "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 类型.

type foo struct {running int32  
}

func (f* foo) start() {if atomic.SwapInt32(&f.running, 1) == 1 {return
  }
  
}

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

type foo struct {running atomic.Bool}

func (f *foo) start() {if f.running.Swap(true) {return
  }
  
}

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

避免使用全局可变对象

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

var _timeNow = time.Now

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

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

func TestSign(t *testing.T) {
  oldTimeNow := _timeNow
  _timeNow = func() time.Time {return someFixedTime
  }
  defer func() { _timeNow = oldTimeNow}()

  assert.Equal(t, want, sign(give))
}

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

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

避免在公共结构体中内嵌类型

嵌入类型会暴露实现细节，无法类型演化，让文档也变得模糊。

假设你用 AbstractList 结构体实现了公共的 list 方法，避免在其他实现中内嵌 AbstractList 类型。而是应该在其他结构体中显式声明 list，并在方法实现中调用 list 的方法。

type AbstractList struct {}


func (l *AbstractList) Add(e Entity) { }


func (l *AbstractList) Remove(e Entity) { }

type ConcreteList struct {*AbstractList}

type ConcreteList struct {list *AbstractList
}


func (l *ConcreteList) Add(e Entity) {l.list.Add(e)
}


func (l *ConcreteList) Remove(e Entity) {l.list.Remove(e)
}

Go 允许内嵌类型 type embedding 作为组合和继承的折中方案。外部的结构体会获得内嵌类型的隐式拷贝。默认情况下，内嵌类型的方法会嵌入实例的同一方法。

外部的结构体会获取嵌入类型的同名字段。如果嵌入类型的字段是公开 (public) 的，那嵌入后也是公开的。为保证向后兼容性，外部结构体未来每个版本都需要保留嵌入类型。

很少场景需要嵌入类型，虽然嵌入类型很方便，让你避免编写冗长的方法。

即使是用 interface 而不是结构体来嵌入方法，这是给开发人员带来了一定的灵活性，但是仍然暴露了具体实现列表的抽象细节。

type AbstractList interface {Add(Entity)
  Remove(Entity)
}


type ConcreteList struct {AbstractList}

type ConcreteList struct {list AbstractList
}


func (l *ConcreteList) Add(e Entity) {l.list.Add(e)
}


func (l *ConcreteList) Remove(e Entity) {l.list.Remove(e)
}

不管是嵌入结构体还是嵌入接口，都会限制类型的演化。

• 若嵌入接口，当你增加一个方法是一种破坏性改变
• 若嵌入结构体，当你删除一个方法是一种破坏性改变
• 删除嵌入类型是一种破坏性改变
• 即使用满足接口约束的类型去替换嵌入类型，也是一种破坏性改变

尽管编写内嵌类型已实现的方法是乏味的。但是这些工作隐藏了实现细节，留下了更多更改的机会，并消除了在文档中发现完整 List 接口的间接方法。

避免使用内建命名

Go 语言的 spec 中列举了一些内建命名，在你的 Go 程序中应该避免使用预声明的标识符；

根据上下文的不同，用预声明标识符命名变量可能会在当前作用域下覆盖官方标识符，让你的代码变得难以理解。最好的情况下，编译器会直接报错，最糟糕的情况下，这样的代码会引入难以排查的 bug。

var error string




func handleErrorMessage(error string) { }

var errorMessage string




func handleErrorMessage(msg string) { }

type Foo struct {
    
    
    
    
    error  error
    string string
}

func (f Foo) Error() error {return f.error
}

func (f Foo) String() string {return f.string
}

type Foo struct {
    
    
    err error
    str string
}

func (f Foo) Error() error {return f.err
}

func (f Foo) String() string {return f.str
}

注意当你使用预声明标识符时编译器不会报错，但是像 go vet 这样的工具会告诉你标识符被覆盖的情况。

避免使用 init()

尽可能避免使用 init()。如果实在依赖 init()，可以使用以下方式：

1. 不管程序环境或调用方式如何，初始化要完全确定。
2. 避免依赖其他 init()函数的顺序或者产生的结果。虽然 init()顺序是明确的，但是代码可以更改。init()函数之间的关系会让代码变得易错和脆弱。
3. 避免读写全局变量、环境变量，比如机器信息、环境变量、工作目录，程序的参数和输入等等。
4. 避免 I/O 操作，比如文件系统，网络和系统调用。

如果代码不能满足这些需求，那可能属于帮助代码，需要作为 main()函数的一部分进行调用(或者封装初始化逻辑，让 main 函数去调用)。需要注意的是，被其他模块依赖的代码应该完全指定初始化顺序的确定性，而不是依赖 ” 初始化魔法 ”。

type Foo struct { }

var _defaultFoo Foo

func init() {_defaultFoo = Foo{}
}

var _defaultFoo = Foo{ }



var _defaultFoo = defaultFoo()

func defaultFoo() Foo {return Foo{}}

type Config struct { }

var _config Config

func init() {cwd, _ := os.Getwd()

    
    raw, _ := os.ReadFile(path.Join(cwd, "config", "config.yaml"),
    )

    yaml.Unmarshal(raw, &_config)
}

type Config struct { }

func loadConfig() Config {cwd, err := os.Getwd()
    

    raw, err := os.ReadFile(path.Join(cwd, "config", "config.yaml"),
    )
    

    var config Config
    yaml.Unmarshal(raw, &config)

    return config
}

但是在某些情况下，init()函数可能更具优势：

• 单个赋值语句中无法表示的复杂表达式
• 插件钩子，比如 database/sql，编码信息注册表等
• 对 Google Cloud Functions 和其他形式确定性预计算的优化

优雅退出主函数

Go 程序使用 os.Exit 或 log.Fatal* 来立即退出。(Panic 不是优雅的程序退出方式，可以参考 don’t panic)

应该只在 main()函数里调用 os.Exit 或 log.Fatal* 函数。其他函数应该返回错误来表示失败，在 main 中进行退出。

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

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
}

程序中多个函数都能退出的话会有一些问题：

• 不明显的控制流：多个函数都能退出的话，找出程序的控制流会变得困难。
• 测试困难：如果一个函数让程序退出，那它也会让测试退出。这样会让函数难以测试。而且可能会让 go text 无法测试其他函数。
• 跳过清理：当一个函数退出程序时，会跳过已经进入 defer 队列的函数调用。这样会增加跳过清理任务的风险。

一次性退出

有条件的情况下，main()函数中最好只调用 os.Exit 或 log.Fatal 一次。如果有多种错误情况会停止 程序的执行，将这些错误放在一个独立的函数中，并返回错误，main()中处理错误并退出。

把所有的关键逻辑放在一个独立的可测试的函数中，会让你的 main()函数变得简短。

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

  
  

  b, err := io.ReadAll(f)
  if err != nil {log.Fatal(err)
  }

  
}

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
  }

  
}

在序列化结构体中使用字段标签。

要编码成 JSON、YAML 或其他支持 tag 格式的结构体字段应该用指定对应项 tag 标签进行注释。

type Stock struct {Price int
  Name  string
}

bytes, err := json.Marshal(Stock{Price: 137,
  Name:  "UBER",
})

type Stock struct {Price int    `json:"price"`
  Name  string `json:"name"`
  
}

bytes, err := json.Marshal(Stock{Price: 137,
  Name:  "UBER",
})

Rationale: 结构体的序列化方式是不同系统通信的契约。修改结构体的结构和字段会破坏这个契约。在结构体中声明 tag 可以防止重构结构体中意外违反约定。

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

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

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

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

make(map[T1]T2, hint)

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

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

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

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

make([]T, length, capacity)

for n := 0; n make([]int, 0)
  for k := 0; k append(data, k)
  }
}

for n := 0; n make([]int, 0, size)
  for k := 0; k append(data, k)
  }
}

BenchmarkBad-4    100000000    2.48s

BenchmarkGood-4   100000000    0.21s

import "a"
import "b"

import ("a"
  "b"
)

const a = 1
const b = 2



var a = 1
var b = 2



type Area float64
type Volume float64

const (a = 1
  b = 2
)

var (a = 1
  b = 2
)

type (Area float64
  Volume float64
)

type Operation int

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

type Operation int

const (Add Operation = iota + 1
  Subtract
  Multiply
)

const EnvVar = "MY_ENV"

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

  
}

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

  
}

func (c *client) request() {caller := c.name
  format := "json"
  timeout := 5*time.Second
  var err error

  // ...
}

func (c *client) request() {
  var (caller  = c.name
    format  = "json"
    timeout = 5*time.Second
    err error
  )

  // ...
}

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

import ("fmt"
  "os"

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

import ("net/http"

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

import ("fmt"
  "os"


  nettrace "golang.net/x/trace"
)

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

  nettrace "golang.net/x/trace"
)

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

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

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

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

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

a := 10
if b {a = 100
}

var _s string = F()

func F() string {return "A" }

var _s = F()



func F() string {return "A" }

type myError struct{}

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

func F() myError { return myError{}}

var _e error = F()

const (defaultPort = 8080
  defaultUser = "user"
)



func Bar() {defaultPort := 9090
  ...
  fmt.Println("Default port", defaultPort)

  
  
}

const (_defaultPort = 8080
  _defaultUser = "user"
)

type Client struct {version int
  http.Client
}

type Client struct {
  http.Client

  version int
}

type A struct {sync.Mutex}

type countingWriteCloser struct {
    
    
    
    
    io.WriteCloser

    count int
}

func (w *countingWriteCloser) Write(bs []byte) (int, error) {w.count += len(bs)
    return w.WriteCloser.Write(bs)
}

type Book struct {io.ReadWriter}



var b Book
b.Read(...)  
b.String()   
b.Write(...) 

type Book struct {bytes.Buffer}



var b Book
b.Read(...)  
b.String()   
b.Write(...) 

type Client struct {
    sync.Mutex
    sync.WaitGroup
    bytes.Buffer
    url.URL
}

type Client struct {
    mtx sync.Mutex
    wg  sync.WaitGroup
    buf bytes.Buffer
    url url.URL
}

var s = "foo"

s := "foo"

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

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

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

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

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

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

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

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

fmt.Println(cfg)
return nil

printInfo("foo", true, true)

printInfo("foo", true , true )

type Region int

const (UnknownRegion Region = iota
  Local
)

type Status int

const (StatusReady Status = iota + 1
  StatusDone
  
)

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

wantError := "unknown name:"test""

wantError := `unknown error:"test"`

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

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

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

user := User{FirstName: "John",
  LastName: "Doe",
  MiddleName: "",
  Admin: false,
}

user := User{
  FirstName: "John",
  LastName: "Doe",
}

tests := []struct{give string
  want int
}{{give: "0", want: 0},
  
}

user := User{}

var user User

sval := T{Name: "foo"}


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

sval := T{Name: "foo"}

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

var (m1 = map[T1]T2{}
  m2 map[T1]T2
)

var (m1 = make(map[T1]T2)
  m2 map[T1]T2
)

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

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

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

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

$ go vet -printfuncs=wrapf,statusf

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)

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 := []struct{give     string
  wantHost string
  wantPort string
}{ }

for _, tt := range tests { }

tests := []struct{give string
  
}{ }

for _, tt := range tests {
  tt := tt 
  t.Run(tt.give, func(t *testing.T) {t.Parallel()
    
  })
}

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

type Option interface { }

func WithCache(c bool) Option { }

func WithLogger(log *zap.Logger) Option { }


func Open(addr string,
  opts ...Option,
) (*Connection, error) { }

db.Open(addr, db.DefaultCache, zap.NewNop())
db.Open(addr, db.DefaultCache, log)
db.Open(addr, false , zap.NewNop())
db.Open(addr, false , log)

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

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


func Open(addr string,
  opts ...Option,
) (*Connection, error) {
  options := options{
    cache:  defaultCache,
    logger: zap.NewNop(),}

  for _, o := range opts {o.apply(&options)
  }

  
}