智加文档

Appearance

Return to top
On this page

编码规范

避免过长的行

避免使用需要读者水平滚动或过度转动头部的代码行。

我们建议将行长度限制为 99 characters (99 个字符). 作者应该在达到这个限制之前换行， 但这不是硬性限制。 允许代码超过此限制。

一致性

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

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

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

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

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

相似的声明放在一组

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

import 分组

导入应该分为两组：

  • 标准库
  • 其他库

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

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

包名

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

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

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

函数名

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

导入别名

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

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

函数分组与顺序

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

因此，导出的函数应先出现在文件中，放在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 {...}

减少嵌套

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

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

不必要的 else

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

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

顶层变量声明

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

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

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

go
type myError struct{}
func (myError) Error() string { return "error" }
func F() myError { return myError{} }
var _e error = F()
// F 返回一个 myError 类型的实例，但是我们要 error 类型

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

在未导出的顶级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。 参见错误命名。

结构体中的嵌入

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

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
}

本地变量声明

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

BadGood
go
var s = "foo"
go
s := "foo"

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

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

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，另一个不是），并且在不同的情况下（例如序列化），这两个切片的处理方式可能不同。

缩小变量作用域

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

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

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

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

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

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

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)

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

Go 支持使用 原始字符串字面值，也就是 " ` " 来表示原生字符串，在需要转义的场景下，我们应该尽量使用这种方案来替换。 可以跨越多行并包含引号。使用这些字符串可以避免更难阅读的手工转义的字符串。

BadGood
```go wantError := "unknown name:\"test\"" ``` ```go wantError := `unknown error:"test"` ```
## 初始化结构体 ### 使用字段名初始化结构 初始化结构时，几乎应该始终指定字段名。目前由 [`go vet`] 强制执行。 [`go vet`]: https://golang.org/cmd/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"},
}

省略结构中的零值字段

初始化具有字段名的结构时，除非提供有意义的上下文，否则忽略值为零的字段。 也就是，让我们自动将这些设置为零值

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

对零值结构使用 var

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

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

这将零值结构与那些具有类似于为 初始化 Maps 创建的，区别于非零值字段的结构区分开来， 并与我们更喜欢的 声明空切片 方式相匹配。

初始化 Struct 引用

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

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

初始化 Maps

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

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 容量)。

字符串 string format

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

命名 Printf 样式的函数

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

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

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

shell
$ go vet -printfuncs=wrapf,statusf

另请参阅 go vet: Printf family check.

编程模式

表驱动测试

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

BadGood
go
// func TestSplitHostPort(t *testing.T)
host, port, err := net.SplitHostPort("192.0.2.0:8000")
require.NoError(t, err)
assert.Equal(t, "192.0.2.0", host)
assert.Equal(t, "8000", port)
host, port, err = net.SplitHostPort("192.0.2.0:http")
require.NoError(t, err)
assert.Equal(t, "192.0.2.0", host)
assert.Equal(t, "http", port)
host, port, err = net.SplitHostPort(":8000")
require.NoError(t, err)
assert.Equal(t, "", host)
assert.Equal(t, "8000", port)
host, port, err = net.SplitHostPort("1:8")
require.NoError(t, err)
assert.Equal(t, "1", host)
assert.Equal(t, "8", port)
go
// func TestSplitHostPort(t *testing.T)
tests := []struct{
  give     string
  wantHost string
  wantPort string
}{
  {
    give:     "192.0.2.0:8000",
    wantHost: "192.0.2.0",
    wantPort: "8000",
  },
  {
    give:     "192.0.2.0:http",
    wantHost: "192.0.2.0",
    wantPort: "http",
  },
  {
    give:     ":8000",
    wantHost: "",
    wantPort: "8000",
  },
  {
    give:     "1:8",
    wantHost: "1",
    wantPort: "8",
  },
}
for _, tt := range tests {
  t.Run(tt.give, func(t *testing.T) {
    host, port, err := net.SplitHostPort(tt.give)
    require.NoError(t, err)
    assert.Equal(t, tt.wantHost, host)
    assert.Equal(t, tt.wantPort, port)
  })
}

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

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

go
tests := []struct{
  give     string
  wantHost string
  wantPort string
}{
  // ...
}
for _, tt := range tests {
  // ...
}

并行测试，比如一些专门的循环（例如，生成goroutine或捕获引用作为循环体的一部分的那些循环） 必须注意在循环的范围内显式地分配循环变量，以确保它们保持预期的值。

go
tests := []struct{
  give string
  // ...
}{
  // ...
}
for _, tt := range tests {
  tt := tt // for t.Parallel
  t.Run(tt.give, func(t *testing.T) {
    t.Parallel()
    // ...
  })
}

在上面的例子中，由于下面使用了t.Parallel()，我们必须声明一个作用域为循环迭代的tt变量。 如果我们不这样做，大多数或所有测试都会收到一个意外的tt值，或者一个在运行时发生变化的值。

智加文档规范

Copyright © 2022 - 浙江智加信息科技有限公司