Tenormis's Blog

Appearance

uber-go/guide ​

GitHub - uber-go/guide

1. 版本 ​

当前更新版本：2022-10-19 版本地址：commit:#158

2. 介绍 ​

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

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

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

我们的目标是使代码示例能够准确地用于 Go 的两个发布版本 releases。

所有代码都应该通过 golint 和 go vet 的检查并无错误。我们建议您将编辑器设置为：

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

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

3. 规范 ​

3.1. 避免过长的行 ​

避免使用需要读者水平滚动或过度转动头部的代码行。我们建议将行长度限制为 99 characters（99 个字符），应该在达到这个限制之前换行，但这不是硬性限制。

3.2. 声明分组 ​

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

    BadGood
    Go
    import "a"
import "b"
    Go
    import (
  "a"
  "b"
)

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

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

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

    BadGood
    Go
    type Operation int

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

const (
  Add Operation = iota + 1
  Subtract
  Multiply
)

const EnvVar = "MY_ENV"

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

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

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

  ...
}

  • 例外：如果变量声明与其它变量相邻，则应将变量声明（尤其是函数内部的声明）分组在一起。对一起声明的变量执行此操作，即使它们不相关：

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

3.3. import 分组 ​

导入应该分为两组：

  • 标准库
  • 其它库
BadGood
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"
)

3.4. 包名 ​

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

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

另请参阅 Go 包、Go 包命名规则和 Go 包样式指南。

3.5. 导入别名 ​

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

Go
import (
  "net/http"

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

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

BadGood
Go
import (
  "fmt"
  "os"

  nettrace "golang.net/x/trace"
)
Go
import (
  "fmt"
  "os"
  "runtime/trace"

  nettrace "golang.net/x/trace"
)

3.6. 避免使用内置名称 ​

Go 语言规范概述了几个内置的，不应在 Go 项目中使用的预先声明的标识符。

根据上下文，重用这些标识符作为名称将在当前词法作用域（以及任何嵌套作用域）中隐藏原始标识符，或者使受影响的代码变得混乱。在最好的情况下，编译器会报错；在最坏的情况下，这样的代码可能会引入潜在的、难以捉摸的 BUG。

BadGood
Go
var error string
// `error` 作用域隐式覆盖

// or

func handleErrorMessage(error string) {
    // `error` 作用域隐式覆盖
}
Go
var errorMessage string
// `error` 指向内置的非覆盖

// or

func handleErrorMessage(msg string) {
    // `error` 指向内置的非覆盖
}
Go
type Foo struct {
    // 虽然这些字段在技术上不构成阴影
    // 但 `error` 或 `string` 字符串的重映射现在是不明确的。
    error  error
    string string
}

func (f Foo) Error() error {
    // `error` 和 `f.error` 在视觉上是相似的
    return f.error
}

func (f Foo) String() string {
    // `string` and `f.string` 在视觉上是相似的
    return f.string
}
Go
type Foo struct {
    // `error` and `string` 现在是明确的。
    err error
    str string
}

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

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

注意，当使用预先声明的标识符时，编译器不会生成错误，但是诸如 go vet 之类的工具会正确地指出这些以及其它情况下的隐藏问题。

3.7. 包内全局常量变量 ​

在未导出的顶级 vars 和 consts，前面加上前缀 _ 以便跟局部变量进行区分。

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

BadGood
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"
)

例外：未导出的错误值可以使用不带下划线的前缀 err，参见 Error 命名。

3.8. 避免可变全局变量 ​

使用选择依赖注入方式避免改变全局变量，既适用于函数指针又适用于其它值类型。

BadGood
Go
// sign.go
var _timeNow = time.Now

func sign(msg string) string {
  now := _timeNow()
  return signWithTime(msg, now)
}
Go
// sign.go
type signer struct {
  now func() time.Time
}

func newSigner() *signer {
  return &signer{
    now: time.Now,
  }
}

func (s *signer) Sign(msg string) string {
  now := s.now()
  return signWithTime(msg, now)
}
Go
// sign_test.go
func TestSign(t *testing.T) {
  oldTimeNow := _timeNow
  _timeNow = func() time.Time {
    return someFixedTime
  }
  defer func() { _timeNow = oldTimeNow }()
  assert.Equal(t, want, sign(give))
}
Go
// sign_test.go
func TestSigner(t *testing.T) {
  s := newSigner()
  s.now = func() time.Time {
    return someFixedTime
  }
  assert.Equal(t, want, s.Sign(give))
}

3.9. 避免使用 init() ​

尽可能避免使用 init()。当 init() 是不可避免或可取的，代码应先尝试：

  1. 无论程序环境或调用如何，都是完全确定的；
  2. 避免依赖于其它 init() 函数的顺序或副作用。虽然 init() 顺序是明确的，但代码可以更改，因此 init() 函数之间的关系可能会使代码变得脆弱和容易出错；
  3. 避免访问/操作全局、环境状态，如机器信息、环境变量、工作目录、程序参数/输入等；
  4. 避免 I/O，包括文件系统、网络和系统调用；

不能满足这些要求的代码可能属于要作为 main() 调用的一部分（或程序生命周期中的其它地方），或者作为 main() 本身的一部分写入。特别是，打算由其它程序使用的库应该特别注意完全确定性，而不是施展 “init 魔法”（下面第二个例子）。

BadGood
Go
type Foo struct {
    // ...
}

var _defaultFoo Foo

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

// or，为了更好的可测试性：
var _defaultFoo = defaultFoo()

func defaultFoo() Foo {
    return Foo{
        // ...
    }
}
Go
type Config struct {
    // ...
}

var _config Config

func init() {
    // Bad: 基于当前目录
    cwd, _ := os.Getwd()
    // Bad: I/O
    raw, _ := os.ReadFile(
        path.Join(cwd, "config", "config.yaml"),
    )
    yaml.Unmarshal(raw, &_config)
}
Go
type Config struct {
    // ...
}

func loadConfig() Config {
    cwd, err := os.Getwd()
    // handle err
    raw, err := os.ReadFile(
        path.Join(cwd, "config", "config.yaml"),
    )
    // handle err
    var config Config
    yaml.Unmarshal(raw, &config)
    return config
}

考虑到上述情况，在某些情况下，init() 可能更可取或是必要的，可能包括：

  • 不能表示为单个赋值的复杂表达式；
  • 可插入的钩子，如 database/sql、编码类型注册表等；
  • 对 Google Cloud Functions 和其它形式的确定性预计算的优化；

3.10. 本地变量声明 ​

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

BadGood
Go
var s = "foo"
Go
s := "foo"

但是，在某些情况下，var 使用关键字时默认值会更清晰。参考：声明空切片和 Go nil 切片。

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

3.11. 缩小变量作用域 ​

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

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

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

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

  fmt.Println(cfg)
  return nil
} else {
  return err
}
    Go
    data, err := os.ReadFile(name)
if err != nil {
   return err
}

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

fmt.Println(cfg)
return nil

3.12. 程序退出方式 ​

Go 程序使用 os.Exit 或者 log.Fatal* 立即退出程序（仅在 main() 中调用 os.Exit 或 log.Fatal*，不要在其它函数中调用），请不要使用 panic退出程序。

BadGood
Go
func main() {
  body := readFile(path)
  fmt.Println(body)
}

func readFile(path string) string {
  f, err := os.Open(path)
  if err != nil {
    log.Fatal(err)
  }
  b, err := os.ReadAll(f)
  if err != nil {
    log.Fatal(err)
  }
  return string(b)
}
Go
func main() {
  body, err := readFile(path)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(body)
}

func readFile(path string) (string, error) {
  f, err := os.Open(path)
  if err != nil {
    return "", err
  }
  b, err := os.ReadAll(f)
  if err != nil {
    return "", err
  }
  return string(b), nil
}

具有多个退出函数的程序会存在一些问题：

  • 不明显的控制流：任何函数都可以退出程序，因此很难对控制流进行推理；
  • 难以测试：退出程序的函数也将退出调用它的测试，这使得函数很难测试，并引入了跳过 go test 尚未运行的其它测试的风险；
  • 跳过清理：当函数退出程序时，会跳过已经进入 defer 队列里的函数调用，这增加了跳过重要清理任务的风险；

如果可能的话，你的 main() 函数中最多只有一次调用 os.Exit 或者 log.Fatal，如果有多个错误场景停止程序执行，请将该逻辑放在单独的函数下并从中返回错误。这可以缩短 main() 函数，并将所有关键业务逻辑放入一个单独的、可测试的函数中。

BadGood
Go
package main

func main() {
  args := os.Args[1:]
  if len(args) != 1 {
    log.Fatal("missing file")
  }
  name := args[0]
  f, err := os.Open(name)
  if err != nil {
    log.Fatal(err)
  }
  defer f.Close()
  // 如果我们调用 log.Fatal 在这条线之后
  // f.Close 将会被执行。
  b, err := os.ReadAll(f)
  if err != nil {
    log.Fatal(err)
  }
  // ...
}
Go
package main

func main() {
  if err := run(); err != nil {
    log.Fatal(err)
  }
}

func run() error {
  args := os.Args[1:]
  if len(args) != 1 {
    return errors.New("missing file")
  }
  name := args[0]
  f, err := os.Open(name)
  if err != nil {
    return err
  }
  defer f.Close()
  b, err := os.ReadAll(f)
  if err != nil {
    return err
  }
  // ...
}

3.13. 函数、方法名 ​

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

3.14. 函数、方法分组与顺序 ​

  • 函数、方法应按粗略的调用顺序排序；
  • 同一文件中的方法应按接收者分组；

因此，导出的方法应放在 struct、const、var 定义的后面。在定义类型之后，但在接收者的其余方法之前，可能会出现一个 newXYZ()/NewXYZ()。由于方法是按接收者分组的，因此普通工具函数应在文件末尾出现。

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

3.15. 避免参数语义不明确 ​

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

BadGood
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）。

Go
type Region int

const (
  UnknownRegion Region = iota
  Local
)

type Status int

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

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

3.16. 减少嵌套 ​

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

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

3.17. 不必要的 else ​

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

BadGood
Go
var a int
if b {
  a = 100
} else {
  a = 10
}
Go
a := 10
if b {
  a = 100
}

3.18. Printf 外的格式字符串 ​

如果你在函数外声明 Printf 风格（printf-style）函数的格式字符串，请将其设置为 const 常量。这有助于 go vet 对格式字符串执行静态分析。

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

3.19. 命名 Printf 风格的函数 ​

声明 Printf 风格的函数时，请确保 go vet 可以检测到它并检查格式字符串。

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

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

Bash
$ go vet -printfuncs=wrapf,statusf

另请参阅 go vet: Printf family check。

3.20. Error 类型 ​

声明错误的选项很少，在选择最适合的选项之前，请考虑以下事项：

  • 调用者是否需要匹配错误以便他们可以处理它？

    如果是，我们必须通过声明顶级错误变量或自定义类型来支持 errors.Is 或 errors.As 函数。

  • 错误消息是否为静态字符串，还是需要上下文信息的动态字符串？

    如果是静态字符串，我们可以使用 errors.New，但对于后者，我们必须使用 fmt.Errorf 或自定义错误类型。

  • 我们是否正在传递由下游函数返回的新错误？

    如果是这样，请参阅Error 包装小节。

错误匹配错误消息指导
Nostaticerrors.New
Nodynamicfmt.Errorf
Yesstatictop-level var with errors.New
Yesdynamiccustom error type

  1. 静态字符串的错误处理：

    • 如果调用者无需匹配并处理此错误，则使用 errors.New 表示；
    • 如果调用者需要匹配并处理此错误，则将此错误导出为变量以支持将其与 errors.Is 匹配；
    无错误匹配错误匹配
    Go
    // package foo
func Open() error {
  return errors.New("could not open")
}

// package bar
if err := foo.Open(); err != nil {
  // Can't handle the error.
  panic("unknown error")
}
    Go
    // package foo
var ErrCouldNotOpen = errors.New("could not open")

func Open() error {
  return ErrCouldNotOpen
}

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

  2. 动态字符串的错误处理：

    • 如果调用者无需匹配并处理此错误，则使用 fmt.Errorf；
    • 如果调用者需要匹配并处理此错误，则自定义 error；
    无错误匹配错误匹配
    Go
    // package foo
func Open(file string) error {
  return fmt.Errorf("file %q not found", file)
}

// package bar
if err := foo.Open("testfile.txt"); err != nil {
  // Can't handle the error.
  panic("unknown error")
}
    Go
    // package foo
type NotFoundError struct {
  File string
}

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

func Open(file string) error {
  return &NotFoundError{File: file}
}

// package bar
if err := foo.Open("testfile.txt"); err != nil {
  var notFound *NotFoundError
  if errors.As(err, &notFound) {
    // handle the error
  } else {
    panic("unknown error")
  }
}

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

3.21. Error 包装 ​

如果调用其它方法时出现错误，通常有三种处理方式可以选择：

  • 将原始错误原样返回；
  • 使用 fmt.Errorf 搭配 %w 将错误添加进上下文后返回；
  • 使用 fmt.Errorf 搭配 %v 将错误添加进上下文后返回；

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

  • 如果调用者应该可以访问底层错误，请使用 %w；

    对于大多数包装错误，这是一个很好的默认值，但请注意，调用者可能会开始依赖此行为。因此，对于包装错误是已知 var 或类型的情况，请将其作为函数契约的一部分进行记录和测试。

  • 使用 %v 来混淆底层错误；

    调用者将无法匹配它，但如果需要，您可以在将来切换到 %w。

在为返回的错误添加上下文时，通过避免使用 "failed to" 之类的短语来保持上下文简洁，当错误通过堆栈向上渗透时，它会一层一层被堆积起来：

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

然而，一旦错误被发送到另一个系统，应该清楚消息是一个错误（例如 err 标签或日志中的 "Failed" 前缀）。

另见不要只检查错误，优雅地处理它们。

3.22. Error 命名 ​

对于存储为全局变量的错误值，根据是否导出，使用前缀 Err 或 err。

Go
var (
  // 导出以下两个错误，以便此包的用户可以将它们与 errors.Is 进行匹配。

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

  // 这个错误没有被导出，因为我们不想让它成为我们公共 API 的一部分。我们可能仍然在带有错误的包内使用它。
  errNotFound = errors.New("not found")
)

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

Go
// 同样，这个错误被导出，以便这个包的用户可以将它与 errors.As 匹配。
type NotFoundError struct {
  File string
}

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

// 并且这个错误没有被导出，因为我们不想让它成为公共 API 的一部分。我们仍然可以在带有 errors.As 的包中使用它。
type resolveError struct {
  Path string
}

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

3.23. 处理断言失败 ​

类型断言将会在检测到不正确的类型时，以单一返回值形式返回 panic。因此，请始终使用 “逗号 ok” 习语。

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

3.24. 不要使用 panic ​

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

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

func main() {
  run(os.Args[1:])
}
Go
func run(args []string) error {
  if len(args) == 0 {
    return errors.New("an argument is required")
  }
  // ...
  return nil
}

func main() {
  if err := run(os.Args[1:]); err != nil {
    fmt.Fprintln(os.Stderr, err)
    os.Exit(1)
  }
}

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

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

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

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

另请参阅：什么时候该用不该用 panic。

3.25. 枚举从 1 开始 ​

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

BadGood
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

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

Go
type LogOutput int

const (
  LogToStdout LogOutput = iota
  LogToFile
  LogToRemote
)

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

3.26. 字符串字面值 ​

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

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

BadGood
Go
wantError := "unknown name:\"test\""
Go
wantError := `unknown error:"test"`

3.27. 优先使用 strconv 而不是 fmt ​

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

BadGood
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())
}
Text
BenchmarkFmtSprint-4    143 ns/op    2 allocs/op
Text
BenchmarkStrconv-4    64.2 ns/op    1 allocs/op

3.28. 避免字符串到字节的转换 ​

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

BadGood
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)
}
Text
BenchmarkBad-4   50000000   22.2 ns/op
Text
BenchmarkGood-4  500000000   3.25 ns/op

3.29. 初始化 Maps ​

对于空 map 请使用 make() 初始化，并且 map 是通过编程方式填充的。这使得 map 初始化在表现上不同于声明，并且它还可以方便地在 make 后添加大小提示。

BadGood
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 初始化列表）初始化映射。

BadGood
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 容量）。

3.30. 指定 Map 容量提示 ​

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

Go
make(map[T1]T2, hint)

向 make() 提供容量提示会在初始化时尝试调整 map 的大小，这将减少在将元素添加到 map 时为 map 重新分配内存。

注意，与 slices 不同。map 的容量并不保证完全分配，而是用于估计所需的 hashmap bucket 的数量。因此，在将元素添加到 map 时，甚至在指定 map 容量时，仍可能发生分配。

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

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

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

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

m 是在没有大小提示的情况下创建的，在运行时可能会产生更多的重新分配。

m 是有大小提示的情况下创建的，在运行时可能会有较少的重新分配。

3.31. 指定 Slice 容量 ​

在尽可能的情况下，在使用 make() 初始化切片时提供容量信息，特别是在追加切片时。

Go
make([]T, length, capacity)

与 maps 不同，slice 的容量并不只是一个提示：编译器将为提供给 make() 的 slice 的容量分配足够的内存，这意味着后续的 append() 操作是零分配（直到 slice 的长度与容量相等，在此之后，任何 append 都可能调整大小以容纳其它元素）。

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

3.32. nil 是一个有效的 slice ​

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

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

    BadGood
    Go
    if x == "" {
  return []int{}
}
    Go
    if x == "" {
  return nil
}

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

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

  • 零值切片（用 var 声明的切片）即可立即使用，无需通过 make()、字面值的方式进行创建；

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

记住，虽然 nil 切片是有效的切片，但它不等于长度为 0 的切片（一个为 nil，另一个不是），并且在不同的情况下（例如序列化），这两个切片的处理方式可能不同，参考：Go nil 切片。

3.33. 拷贝 slices 和 maps ​

  1. 当 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] = ...

  2. 同样在返回 slices 或 maps 时，请注意用户对暴露内部状态的 map 或 slice 的修改；

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

3.34. 使用 time 处理时间 ​

在处理时间时始终使用 time 包，因为它有助于以更安全、更准确的方式处理这些不正确的假设。

  1. 使用 time.Time 表达瞬时时间：

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

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

  2. 使用 time.Duration 表达时间段：

    BadGood
    Go
    func poll(delay int) {
  for {
    // ...
    time.Sleep(time.Duration(delay) * time.Millisecond)
  }
}
poll(10) // 是几秒钟还是几毫秒？
    Go
    func poll(delay time.Duration) {
  for {
    // ...
    time.Sleep(delay)
  }
}
poll(10*time.Second)

    回到第一个例子，在一个时间瞬间加上 24 小时，我们用于添加时间的方法取决于意图。如果我们想要下一个日历日（当前天的下一天）的同一个时间点，我们应该使用 Time.AddDate。但是，如果我们想保证某一时刻比前一时刻晚 24 小时，我们应该使用 Time.Add。

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

  3. 对外部系统使用 time.Time 和 time.Duration；

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

    当不能在这些交互中使用 time.Duration 时，请使用 int 或 float64，并在字段名称中包含单位。例如，由于 encoding/json 不支持 time.Duration，因此该单位包含在字段的名称中：

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

    当在这些交互中不能使用 time.Time 时，除非达成一致，否则使用 string 和 RFC 3339 中定义的格式时间戳。默认情况下，Time.UnmarshalText 使用此格式，并可通过 time.RFC3339 在 Time.Format 和 time.Parse 中使用。

    尽管这在实践中并不成问题，但请记住，time 包不支持解析闰秒时间戳（GitHub - issues 8728），也不在计算中考虑闰秒（GitHub - issues 15190）。如果您比较两个时间瞬间，则差异将不包括这两个瞬间之间可能发生的闰秒。

3.35. 避免在公共结构中嵌入类型 ​

这些嵌入的类型泄漏实现细节、抑制类型进化以及让文档变得难以阅读。

假设您已经使用共享的 AbstractList 实现了各种列表类型，请避免将 AbstractList 嵌入到具体的列表实现中。相反，应在具体的实现列表中手写相应的方法并将其委托给 AbstractList。

Go
type AbstractList struct {}

// 添加将实体添加到列表中。
func (l *AbstractList) Add(e Entity) {
  // ...
}

// 移除从列表中移除实体。
func (l *AbstractList) Remove(e Entity) {
  // ...
}
BadGood
Go
// ConcreteList 是一个实体列表。
type ConcreteList struct {
  *AbstractList
}
Go
// ConcreteList 是一个实体列表。
type ConcreteList struct {
  list *AbstractList
}

// 添加将实体添加到列表中。
func (l *ConcreteList) Add(e Entity) {
  l.list.Add(e)
}

// 移除从列表中移除实体。
func (l *ConcreteList) Remove(e Entity) {
  l.list.Remove(e)
}

无论是使用嵌入结构还是嵌入接口，都会限制类型的演化。尽管编写这些委托方法是乏味的，但是额外的工作隐藏了实现细节，留下了更多的更改机会，并且还消除了在文档中发现完整列表接口的间接性。

3.36. 结构体中的嵌入 ​

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

BadGood
Go
type Client struct {
  version int
  http.Client
}
Go
type Client struct {
  http.Client

  version int
}

内嵌应该提供切实的好处，比如以语义上合适的方式添加或增强功能。它应该在对用户没有任何不利影响的情况下使用。另请参见：避免在公共结构中嵌入类型。

例外：即使在未导出类型中，Mutex 也不应该作为内嵌字段。另请参见：零值 Mutex 是有效的。

嵌入不应该:

  • 纯粹是为了美观或方便；
  • 使外部类型更难构造或使用；
  • 影响外部类型的零值（如果外部类型有一个有用的零值，则在嵌入内部类型之后应该仍然有一个有用的零值）；
  • 从外部类型公开不相关的方法或字段（嵌入内部类型的副作用）；
  • 公开未导出的类型；
  • 影响外部类型的复制形式；
  • 更改外部类型的 API 或类型语义；
  • 嵌入内部类型的非规范形式；
  • 公开外部类型的实现详细信息；
  • 允许用户观察或控制类型内部；
  • 通过包装的方式改变内部方法的一般行为，这种包装方式会给用户带来一些意料之外情况；

简单地说，有意识地和有目的地嵌入。一个好的试金石是 “是否所有这些导出的内部方法/字段都将直接添加到外部类型”，如果答案是 some 或 no，不要嵌入内部类型，改用字段。

BadGood
Go
type A struct {
    // Bad: A.Lock() and A.Unlock() 现在可用
    // 不提供任何功能性好处，并允许用户控制有关 A 的内部细节。
    sync.Mutex
}
Go
type countingWriteCloser struct {
    // Good: Write() 在外层提供用于特定目的，
    // 并且委托工作到内部类型的 Write() 中。
    io.WriteCloser
    count int
}

func (w *countingWriteCloser) Write(bs []byte) (int, error) {
    w.count += len(bs)
    return w.WriteCloser.Write(bs)
}
Go
type Book struct {
    // Bad: 更改了零值的有用性
    io.ReadWriter
    // other fields
}

// later
var b Book
b.Read(...)  // panic: nil pointer
b.String()   // panic: nil pointer
b.Write(...) // panic: nil pointer
Go
type Book struct {
    // Good: 有用的零值
    bytes.Buffer
    // other fields
}

// later
var b Book
b.Read(...)  // ok
b.String()   // ok
b.Write(...) // ok
Go
type Client struct {
    sync.Mutex
    sync.WaitGroup
    bytes.Buffer
    url.URL
}
Go
type Client struct {
    mtx sync.Mutex
    wg  sync.WaitGroup
    buf bytes.Buffer
    url url.URL
}

3.37. 在序列化结构中标记字段 ​

任何序列化到 JSON、YAML 或其它支持基于标记的字段命名的格式应使用相关标记进行注释。

BadGood
Go
type Stock struct {
  Price int
  Name  string
}

bytes, err := json.Marshal(Stock{
  Price: 137,
  Name:  "UBER",
})
Go
type Stock struct {
  Price int    `json:"price"`
  Name  string `json:"name"`
  // Safe to rename Name to Symbol.
}

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

理论上结构的序列化形式是不同系统之间的契约，对序列化表单结构（包括字段名）的更改会破坏此约定。在标记中指定字段名使约定明确，它还可以通过重构或重命名字段来防止意外违反约定。

3.38. 使用字段名初始化结构 ​

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

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

例外：当有 3 个或更少的字段时，测试表中的字段名 may 可以省略。

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

3.39. 省略结构中的零值字段 ​

初始化具有字段名的结构时，除非提供有意义的上下文，否则忽略值为零的字段。也就是，让我们自动将这些设置为零值。这有助于通过省略该上下文中的默认值来减少阅读的障碍，只指定有意义的值。

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

在字段名提供有意义上下文的地方包含零值。例如，表驱动测试中的测试用例可以受益于字段的名称，即使它们是零值的。

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

3.40. 对零值结构使用 var ​

如果在声明中省略了结构的所有字段，请使用 var 声明结构。

BadGood
Go
user := User{}
Go
var user User

这将零值结构与具有非零字段的结构区分开来，类似于初始化 Maps。也与我们所更倾向的声明空切片的方式相匹配。

3.41. 初始化结构引用 ​

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

BadGood
Go
// inconsistent, sval := T{Name: "foo"}
sptr := new(T)
sptr.Name = "bar"
Go
// consistent, sval := T{Name: "foo"}
sptr := &T{Name: "bar"}

3.42. 指向接口的指针 ​

直接将接口作为值进行传递即可，不需要使用指向接口的指针。

3.43. 验证接口实现 ​

利用编译器对接口的检查机制，在编译期检查类型是否符合接口定义。示例：

BadGood
Go
// 如果 Handler 没有实现 http.Handler，会在运行时报错
type Handler struct {
  // ...
}

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

// 用于触发编译期的接口的合理性检查机制
// 如果 Handler 没有实现 http.Handler，会在编译期报错
var _ http.Handler = (*Handler)(nil)

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

如果 *Handler 与 http.Handler 的接口不匹配，那么语句 var _ http.Handler = (*Handler)(nil) 将无法编译通过。

赋值的右边应该是断言类型的零值。例如，对于指针类型（如 *Handler）、切片和映射为 nil；对于结构类型为空结构。

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

var _ http.Handler = LogHandler{}

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

3.44. 接收器与接口 ​

值接收器方法与指针接收器方法的区别。

3.45. 零值 Mutex 是有效的 ​

  1. 零值 sync.Mutex 和 sync.RWMutex 是有效的，不需要使用指向 mutex 的指针；

    BadGood
    Go
    mu := new(sync.Mutex)
mu.Lock()
    Go
    var mu sync.Mutex
mu.Lock()

  2. mutex 在作为结构体字段时：

    • 如果你使用结构体指针，mutex 应该作为结构体的非指针字段；
    • 即使该结构体不被导出，也不要直接把 mutex 嵌入到结构体中；
    BadGood
    Go
    type SMap struct {
  sync.Mutex

  data map[string]string
}

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

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

  return m.data[k]
}
    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]
}

    Mutex 字段，Lock 和 Unlock 方法是 SMap 导出的 API 中不刻意说明的一部分。

    mutex 及其方法是 SMap 的实现细节，对其调用者不可见。

3.46. 使用 go.uber.org/atomic ​

使用 sync/atomic 包的原子操作对原始类型 (int32、int64 等）进行操作，因为很容易忘记使用原子操作来读取或修改变量。go.uber.org/atomic 通过隐藏基础类型为这些操作增加了类型安全性。此外，它包括一个方便的 atomic.Bool 类型。

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

3.47. 使用 defer 释放资源 ​

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

BadGood
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。

3.48. channel 的 size 为 0 或 1 ​

channel 通常 size 应为 1 或是无缓冲的。默认情况下，channel 是无缓冲的，其 size 为零。任何其它 size 都必须经过严格的审查。我们需要考虑如何确定大小，考虑是什么阻止了 channel 在高负载下和阻塞写时的写入，以及当这种情况发生时系统逻辑有哪些变化。

BadGood
Go
// 应该足以满足任何情况！
c := make(chan int, 64)
Go
// 大小：1
c := make(chan int, 1) // 或者
// 无缓冲 channel，大小为 0
c := make(chan int)

3.49. 不要滥用 goroutine ​

Goroutines 是轻量级的，但它们不是免费的：至少，它们会为堆栈和 CPU 的调度消耗内存。虽然这些成本对于 Goroutines 的使用来说很小，但当它们在没有受控生命周期的情况下大量生成时会导致严重的性能问题。具有非托管生命周期的 Goroutines 也可能导致其它问题，例如阻碍未使用的对象被垃圾回收、保留不再使用的资源等等。

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

一般来说，每个 goroutine 必须满足以下两个条件之一:

  • 有一个可预测的停止运行时间；
  • 有一种方法可以向 goroutine 发出信号使其停止运行；

不论是通过哪种方式，都必须有代码来阻塞并等待 goroutine 完成。例如：

BadGood
Go
go func() {
  for {
    flush()
    time.Sleep(delay)
  }
}()
Go
var (
  stop = make(chan struct{}) // 告诉 goroutine 停止
  done = make(chan struct{}) // 告诉我们 goroutine 退出了
)

go func() {
  defer close(done)
  ticker := time.NewTicker(delay)
  defer ticker.Stop()
  for {
    select {
    case <-tick.C:
      flush()
    case <-stop:
      return
    }
  }
}()

// 其它地方 ...
close(stop)  // 指示 goroutine 停止

// 其它地方 ...
<-done       // 等待 goroutine 停止

没有办法阻止这个 goroutine。这将一直运行到应用程序退出。

这个 goroutine 可以用 close(stop) 指示 goroutine 停止，也可以等待它退出 <-done。

3.50. 等待 goroutines 退出 ​

必须有一种方案能等待 goroutine 的退出。有两种常用的方法可以做到这一点：

  • 如果有多个 goroutine：使用 sync.WaitGroup

    Go
    var wg sync.WaitGroup
for i := 0; i < N; i++ {
  wg.Add(1)
  go func() {
    defer wg.Done()
    // ...
  }()
}

// To wait for all to finish:
wg.Wait()

  • 如果只有一个 goroutine：添加另一个 chan struct{}，并在 goroutine 完成后关闭它

    Go
    done := make(chan struct{})
go func() {
  defer close(done)
  // ...
}()

// To wait for the goroutine to finish:
<-done

3.51. 不要在 init() 使用 goroutines ​

init() 函数不应该存在 goroutine。另请参阅避免使用 init()。

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

BadGood
Go
func init() {
  go doWork()
}

func doWork() {
  for {
    // ...
  }
}
Go
type Worker struct{ /* ... */ }

func NewWorker(...) *Worker {
  w := &Worker{
    stop: make(chan struct{}),
    done: make(chan struct{}),
    // ...
  }
  go w.doWork()
}

func (w *Worker) doWork() {
  defer close(w.done)
  for {
    // ...
    case <-w.stop:
      return
  }
}

// Shutdown 告诉 worker 停止运行，并等待它完成。
func (w *Worker) Shutdown() {
  close(w.stop)
  <-w.done
}

当用户导出这个包时，会无条件地生成一个后台 goroutine，并且用户无法控制该 goroutine。

在用户需要时才主动调用生成 Worker，提供了关闭 Worker 的方法，以便用户可以释放该 Worker 使用的资源。

另请参阅等待 goroutines 退出。

4. 编程模式 ​

4.1. Options 模式 ​

Options 模式

4.2. Context 模式 ​

Context 模式

4.3. 表驱动测试 ​

表驱动测试

5. Linting ​

比任何 "blessed" linter 集更重要的是，lint 在一个代码库中始终保持一致。

我们建议至少使用以下 linters，因为我认为它们有助于发现最常见的问题，并在不需要规定的情况下为代码质量建立一个高标准：

5.1. Lint Runners ​

我们推荐 golangci-lint 作为 go-to lint 的运行程序，这主要是因为它在较大的代码库中的性能以及能够同时配置和使用许多规范。这个 repo 有一个示例配置文件 .golangci.yml 和推荐的 linter 设置。

golangci-lint 有 various-linters 可供使用。建议将上述 linters 作为基本 set，我们鼓励团队添加对他们的项目有意义的任何附加 linters。

6. 技巧 ​

6.1. 空结构的应用 ​

  1. 使用 chan struct{} 代替 chan bool 在 goroutines 之间传递信号；

    使用 bool 容易让人不理解该值，true or false，但是使用 chan struct{} 就很清楚，我们不在乎值，只关心发生的事儿，更容易表达清楚一些。

  2. 为了防止 unkeyed 初始化结构，可以添加 _ struct {} 字段：

    Go
    type Q struct {
  X, Y int
  _    struct{}
}

    这样一来，使用 Q{X: 1, Y: 1} 可以，但使用 Q{1, 1} 就会出现编译错误：too few values in struct initializer，同时这样也帮助了 go ver 代码检查。

6.2. 验证接口实现 ​

参考：验证接口实现。

6.3. 限制接口不允许在其它包中实现 ​

以下这个示例中，强制 Study 接口中所有方法只能在当前包中去实现，在其它包中不允许实现。因为接口中有小写方法，所以在其它包无法实现。

Go
package study

type Study interface {
  Listen(message string) string
  i()
}

func Speak(s Study) string {
 return s.Listen("abc")
}

i() 表示一个小写方法，换成其它名字也可以。

如果在另外一个包中定义了一个 stu 结构体，这个结构体实现了 Study 接口中的方法：

Go
type stu struct {
  Name string
}

func (s *stu) Listen(message string) string {
  return s.Name + " 听 " + message
}

func (s *stu) i() {}

func main() {
  message := study.Speak(new(stu))
  fmt.Println(message)
}

运行时提示输出：

Text
./main.go:19:28: cannot use new(stu) (type *stu) as type study.Study in argument to study.Speak:
 *stu does not implement study.Study (missing study.i method)
  have i()
  want study.i()

如果去掉接口中的 i()，则正常输出 听 abc。

参考链接

回答两个被频繁问到的代码写法问题

转载请注明作者和出处

Copyright © 2025-至今 Tenormis