Go 语言编程规范建议（上）

1. 代码总体原则

「编写程序应该以人为本，计算机第二」

​ —— Steve McConnell

​

1.1 清晰第一

清晰性是易于维护、易于重构的程序必须具备的特征。代码首先是给人读的，好的代码应当像文章一样发声朗诵出来。

目前软件维护期成本占整个生命周期成本的 40% ~ 90%。根据业界经验，维护期变更代码的成本，小型系统是开发期的 5 倍，大型系统（100 万行代码以上）可以达到 100 倍。业界的调查指出，开发组平均大约一半的人力用于弥补过去的错误。

一般情况下，代码的可阅读性高于性能，只有确定性能是瓶颈时，才应该主动优化。

1.2 简洁为美

简洁就是易于理解并且易于实现。代码越长越难以看懂，也就越容易在修改时引入错误。写的代码越多，意味着出错的地方越多，也就意味着代码的可靠性越低。因此，提倡大家通过编写简洁明了的代码来提升代码可靠性。

废弃的代码（没有被调用的函数和全局变量）要及时清除，重复代码应该尽可能提炼成函数

1.3 风格一致

**产品所有人共享同一个风格所带来的好处，远远超出为了统一而付出的代价。**在公司已有编程规范的指导下，审慎地编排代码以使代码尽可能清晰，是一项非常重要的技能。如果重构/修改其他风格的代码时，比较明智的做法是根据现有风格继续编写代码，或者使用格式转换工具进行转换成公司内部风格。

2. 规范

2.1 命名规范

命名时需要注意以下三点：

• 学会站在调用者的角度思考，命名争取简洁、且见名知义
• 采用通用、大众熟知的缩写命名。比如 buf 而不是 bufio
• 如果缩写的名字会产生歧义，则放弃或换一个

2.1.1 驼峰命名

• 常量、变量、类型、结构体、接口、函数、方法、属性等，全部使用驼峰法 MixedCaps 或 mixedCaps。Go 语言的公私有统一用大小写开头来区分。

  Bad

  const ROLE_NAME = 10
  

  Good：

  const RoleName = 10
  

注：下划线开头的命名不被接受，但有个例外，为了对相关的测试用例进行分组，函数名可能包含下划线，如：TestMyFunction_WhatIsBeingTested。

2.1.2 常量

• 如果是枚举类型的常量，需要先创建相应类型。

  type Scheme string
  
  const (
      Http  Scheme = "http"
      Https Scheme = "https"
  )
  
  

• 如果模块的功能较为复杂，常量名称容易混淆的情况下，为了更好地区分枚举类型，可以使用完整的前缀。

  type Symbol string
  
  const (
      SymbolAdd Symbol = "+"
      SymbolSub Symbol = "-"
  )
  
  
  
  
  

2.1.3 变量

• 在相对简单的环境（对象数量少、针对性强）中，可以将一些名称由完整单词简写为单个字母。

  注：user 可以简写为 u；userId 可以简写为 uid

• 若变量类型为 bool 类型，则名称应以 Has、Is、Can 或 Allow 开头。

  var isExist, hasConflict, canManager, allowGitHook bool

2.1.4 URL

• URL 命名全部小写
• 用正斜杠 / 表示层级关系
• 使用连字符 - 来提高长路径中名称的可读性
• 不得在 URL 中使用下划线 _
• URL 结尾不应包含正斜杠 /
• 文件扩展名不应包含在 URL 中
• URL 需见名知意，但不可暴露服务器架构

Bad：

/GetUserInfo
/photos_path
/My-Folder/my-doc/
/user/user-list

Good：

/user/list
/user/operator-logs

2.1.5 Error

• Error 类型的命名以 Error 结尾

  type ParseError struct {
      Line, Col int
  }
  

• Error 类型的变量，以 Err 开头

  var ErrBadAction = errors.New("a bad example")
  

2.1.6 接口名

• 按照约定，只包含一个方法的接口应当以该方法的名称加上 -er 后缀来命名，如 Reader、Writer、Formatter/CloseNotifier 等。

  type Reader interface {
  	Read(p []byte) (n int, err error)
  }
  

  注：名词用于接口名，动词用于接口的方法名

2.1.7 文件名

• 整个应用或包的主入口文件应当是 main.go，或与应用名称简写相同。比如：spiker 包的主入口文件是 spiker.go，应用的主入口文件是 main.go。

2.1.8 包名

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

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

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

2.1.9 函数名/方法名

• 不要画蛇添足

• 长命名并不会使其更具可读性，一份有用的说明文档通常比额外的厂名更有价值。

Bad：

once.DoOrWaitUntilDone(f)

Good：

once.Do(f)

2.1.10 导入别名

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

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

2.1.11 变量声明

• 顶层变量声明

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

  Bad：

  var _s string = F()
  
  func F() string { return "A" }
  

  Good：

  var _s = F()
  // 由于 F 已经明确了返回一个字符串类型，因此我们没有必要显式指定_s 的类型
  // 还是那种类型
  
  func F() string { return "A" }
  

• 本地变量声明

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

  Bad ： var s = "foo"

  Good：s := "foo"

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

  Bad：filtered := []int{}

  Good：var filtered []int

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

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

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

  Bad：

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

  Good：

  // foo.go
  
  const (
    _defaultPort = 8080
    _defaultUser = "user"
  )
  

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

2.1.12 其他

• 包内容的名字不使用包名开头，因为无需重复包名。

  http 包提供的 HTTP 服务名为 http.Server，而非 HTTPServer。用户代码通过 http.Server 引用该类型，因此没有歧义。

• 不同包中的类型可以相同，因为客户端可通过包名区分它们。

  例如，标准库中含有多个名为 Reader 的类型，包括 jpeg.Reader、bufio.Reader 和 csv.Reader。每个包名搭配 Reader 都是个不错的类型名。

2.2 结构规范

2.2.1 避免过长的行

避免使用需要读者水平滚动或过度转动头部的代码行。建议将行长度限制为 99 characters（99 个字符）。

注：作者应该在达到这个限制之前换行，但这不是硬性限制。允许代码超过此限制。

2.2.2 一致性

本文中概述的一些标准都欧式客观性的评估，是根据场景、上下文、或者主观性的判断。但是最重要的是，保持一致。

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

相反，在一个代码库中包含多个完全不同或冲突的代码风格会导致维护成本开销、不确定性和认知偏差。所有这些都会直接导致速度降低、代码审查痛苦、而且增加 bug 数量。

2.2.3 相似的声明放在一组

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
    EnvVar = "MY_ENV"
  )
  

  Good：

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

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

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

2.2.5 函数分组与顺序

• 函数应该按粗略的调用顺序排序。

• 同一文件中的函数应该按接受者分组。

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

因此，导出的函数应先出现在文件中，放在 struct, const, var 定义的后面。由于函数是按接受者分组的，因此普通工具函数应该在文件末尾出现。

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

2.2.6 减少嵌套

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

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

2.2.7 不必要的 else

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

Bad：

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

Good：

a := 10
if b {
  a = 100
}

2.2.8 缩小变量作用域

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

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

2.3 使用规范

2.3.1 结构体中的嵌入

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

Bad：

type Client struct {
  version int
  http.Client
}

Good：

type Client struct {
  http.Client

  version int
}

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

嵌入不应该：

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

简单地说，有意识地和有目的地嵌入。一种很好的测试体验是，「是否所有这些导出的内部方法/字段都将直接添加到外部类型」

如果答案是 some 或 no，不要嵌入内部类型 - 而是使用字段。

Bad：

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

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

Good：

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

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

2.3.2 nil 是一个有效的 slice

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

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

  Bad：

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

  Good：

  if x == "" {
    return nil
  }
  

• 不应该明确返回长度为零的切片。应该返回 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 声明的切片）可立即使用，无需调用 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)
  }
  

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

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

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

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

Bad：

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

Good：

wantError := `unknown error:"test"`

2.3.4 避免参数语义不明确

函数调用中的意义不明确的参数可能会损害可读性。当参数名称的含义不明显时，请为参数添加 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 Status= iota + 1
  StatusDone
  // Maybe we will have a StatusInProgress in the future.
)

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

2.3.5 初始化结构体

• 使用字段名初始化结构体

初始化结构体时，应该指定字段名称。现在由 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:

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

Good:

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

这有助于通过省略该上下文的默认值来减少阅读的障碍。只指定有意义的值。

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

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

• 对零值结构使用 var

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

Bad:

user := User{}

Good:

var user User

• 初始化 struct 引用

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

Bad:

sval := T{Name: "foo"}

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

Good:

sval := T{Name: "foo"}

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

2.3.6 初始化 Maps

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

Bad: 声明和初始化看起来非常相似的

var (
  // m1 读写安全;
  // m2 在写入时会 panic
  m1 = map[T1]T2{}
  m2 map[T1]T2
)

**Good:**声明和初始化看起来差别非常大

var (
  // m1 读写安全;
  // m2 在写入时会 panic
  m1 = make(map[T1]T2)
  m2 map[T1]T2
)

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

另外，如果 map 包含固定的元素列表，则使用 map literals(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,
}

注：基本准则是：在初始化时使用 map 初始化列表来添加一组固定的元素。否则使用 make，如果可以，请尽可能指定 map 容量

2.3.7 字符串 string format

如果你在函数外声明 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)

2.3.8 命名 Printf 样式的函数

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

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

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

$ go vet -printfuncs=wrapf,statusf

另请参阅 go vet: Printf family check.

3. Linting

Lint 在一个代码库中始终要保持一致。建议至少使用以下 linters，因为它们有助于发现常见的问题，并在不需要规定的情况下为代码质量建立一个高标准。

• errcheck 以确保错误得到处理
• goimports 格式化代码和管理 imports
• golint 指出常见的文体错误
• govet 分析代码中的常见错误
• staticcheck 各种静态分析检查

4. 碎碎念

• 好不容易来到这个世界上，一定要找到一件让你庆幸你出生的事，一件需要你去做，你愿意竭尽全力去做的事。
• 看似不起眼的日复一日，会在将来的某一天，突然让你看到坚持的意义。
• 想借着这烟火的光亮，做个温暖的人，不卑不亢，清澈善良。

5. 参考资料

• 华为 C 语言编程规范（精华总结）
• Go 语言规范-编码风格（2020）
• Uber Go 语言编程规范
• Go Style Guide
• Effective Go
• Go Common Mistakes
• Go Code Review Comments