go编码指南

本编码指南的灵感来源于Uber-Go风格指南,并对hubble进行了专门的修改。

介绍

这些准则用来规范我们的代码的惯例,这些约定已经超出了gofmt中规定的内容。

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

这记录了我们在CRL中遵循的Go代码中的惯用约定。其中许多是Go的一般指导原则,而其他的则依赖于外部资源:

  1. effective go
  2. The Go common mistakes guide

当运行golint和go vet时,所有代码都应该是无错误的。我们建议您将编辑器设置为:

  • 在保存时运行crlfmt
  • 在检查错误时运行make lintshort

您可以在“Go工具编辑器支持”中找到相关信息:golang/go/wiki/IDEsAndTextEditorPlugins

准则

指向接口的指针

几乎不需要指向接口的指针。您应该将接口作为值传递,底层数据仍然可以是指针。

一个接口由两部分组成:

  1. 指向特定类型信息的指针。你可以认为这是"type"
  2. 数据指针。如果存储的数据是指针,则直接存储。如果存储的数据是值,则存储指向该值的指针。

如果希望接口方法修改基础数据,则必须使用指针。

接收器和接口

一个接收值的方法被指针调用可以和值调用一样。

例如,

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

// You can only call Read using a value
sVals[1].Read()

// This will not compile:
//  sVals[0].Write("test")

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

// You can call both Read and Write using a pointer
sPtrs[1].Read()
sPtrs[1].Write("test")
Similarly, an interface can be satisfied by a pointer, even if the method has a value receiver.

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

// The following doesn't compile, since s2Val is a value, and there is no value receiver for f.
//   i = s2Val

请参考: pointers_vs_values

零值互斥锁是有效的

sync.Mutex和sync.RWMutex的零值是有效的,因此不需要指向互斥锁对象的指针。

错误正确
mu := new(sync.Mutex)
mu.Lock()
var mu sync.Mutex
mu.Lock()

如果结构体使用指针,那么互斥锁可以是非指针字段,或者最好是直接嵌入到结构中。

  • 嵌入为私有类型或需要实现互斥锁接口的类型。
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]
}

当需要时拷贝Map和Slices

Slices和Map包含指向底层数据的指针,因此在将它们作为参数传递或作为值返回时,请注意所有权。

另一方面,不要做不必要拷贝slices,堆分配是非常昂贵的,尽量避免做这个操作。

接收Slices和Maps

用户可以修改一个作为参数接收的map或slice,如果存储了它的引用。

如果API通过引用捕获一个slice,请将其记录在函数头中。

错误的代码:

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

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

// 修改 d1.trips?
trips[0] = ...

正确的:

// SetTrips sets the driver's trips.
// Note that the slice is captured by reference, the
// caller should take care of prevening unwanted aliasing.
func (d *Driver) SetTrips(trips []Trip) { d.trips = trips }

// or:

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

返回Slices和Maps

同样,要小心用户对暴露内部状态的映射或切片的修改。

导出的API应该避免返回具有其他访问器的内部状态,例如当它隐藏在互斥锁后面时。

对于“内部”函数有更大的灵活性,尽管函数名应该反映这一点(参见pkg/util/log中的log.closeFileLocked)。

错误的代码:

type Stats struct {
  sync.Mutex

  counters map[string]int
}

// Snapshot returns the current stats.
func (s *Stats) Snapshot() map[string]int {
  s.Lock()
  defer s.Unlock()

  return s.counters
}

// snapshot is no longer protected by the lock!
snapshot := stats.Snapshot()

正确的代码:

type Stats struct {
  sync.Mutex

  counters map[string]int
}

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

  result := make(map[string]int, len(s.counters))
  for k, v := range s.counters {
    result[k] = v
  }
  return result
}

// Snapshot is now a copy.
snapshot := stats.Snapshot()

延迟清理

使用defer清理文件和锁资源

错误的:

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

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

return newCount

// easy to miss unlocks due to multiple returns

正确的:

p.Lock()
defer p.Unlock()

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

p.count++
return p.count

// more readable

Defer的开销非常小,只有在能够证明函数执行时间是以纳秒为顺序的情况下才应该避免。使用defer可读性比使用defer的微小成本要代价要小。这尤其适用于具有比简单内存访问更多的大型方法,其中其他计算比Defer成本更高。

Channel的大小为1或者None

通道的大小通常应为1或无缓冲。默认情况下,通道是无缓冲的,大小为零。任何其他大小都必须经过高度审查。考虑大小是如何确定的,什么可以防止通道在负载和阻塞写入程序时填满,以及发生这种情况时会发生什么。

错误的:

// Ought to be enough for anybody!
c := make(chan int, 64)

正确的:

// Size of one
c := make(chan int, 1) // or
// Unbuffered channel, size of zero
c := make(chan int)

枚举类型从1开始

在Go中引入枚举的标准方法是使用iota声明自定义类型和常量组。由于变量的默认值为0,所以通常应该在非零值上开始枚举。

错误的:

type Operation int

const (
  Add Operation = iota
  Subtract
  Multiply
)

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

正确的:

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

Error Types

  • errors.New() for errors with simple static strings
  • errors.Newf() for formatted error strings
  • errors.AssertionFailedf() for assertion/internal errors that should be louder than usual
  • Add context on return paths using errors.Wrap()/errors.Wrapf()
  • Add user-directed hints with errors.WithHint()

更多请参考errors包的README。

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

  • 这是一个简单的错误,你不需要额外的信息,这是使用errors.New()
  • 当客户端需要检测和处理这个错误,你应该使用Custom type,并实现Error()方法。
  • 如果需要由下游方法返回时,传递错误请参考error的设计文档。

如果客户端需要检测错误,并且您已经使用errors.New创建了一个简单的错误。请对错误使用var。

错误的:

// package foo

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

// package bar

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

正确的:

// 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
  } else {
    return errors.Wrap(err, "unknown error")
  }
}

如果您有一个客户端可能需要检测的错误,并且希望向该错误添加更多信息(例如,它不是静态字符串),那么您应该使用自定义类型。

错误的:

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

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

正确的:

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() error {
  if err := open(); err != nil {
    var nfErr errNotFound
    if errors.As(err, &nfErr); ok {
      // handle
    } else {
      return errors.Wrap(err, "opening file")
    }
  }
}

Error Wrapping

如果调用失败,有四个主要选项用于传递错误:

  • 如果没有要添加的其他上下文,并且希望保留原始错误类型,则返回原始错误。

  • 使用errors.Wrap添加上下文,以便错误消息提供更多上下文和错误。可以使用Unwrap提取原始错误。

  • 如果调用方不需要检测或处理特定的错误情况,请使用errors.Newf。

  • 使用errors.Handle或errors.NewAssertionErrorWithWrappedErrf隐藏原始原因。

建议在可能的情况下添加上下文,这样就不会出现诸如“connection rejected”之类的模糊错误,而是出现诸如“call service foo:connection rejected”之类的更有用的错误。

将上下文添加到返回的错误时,请避免使用“failed to”这样的短语,以保持上下文的简洁性,这些短语表示明显的错误并随着错误在堆栈中的渗透而堆积:

错误的:

返回信息 failed to x: failed to y: failed to create new store: the error

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

正确的:

返回信息 x: y: new store: the error

s, err := store.New()
if err != nil {
    return errors.Wrap(
        "new store", err)
}

但是,一旦错误被发送到另一个系统,就应该清楚消息是一个错误(例如日志中的错误标签或“失败”前缀)。

Go已经有所发展,并在适用的情况下使用errors.Is()和errors.As()。

Handle Type Assertion Failures

类型断言的单一返回值形式将在不正确的类型上将产生panic。所以,一定要用“comma ok”这个短语。

错误的:

t := i.(string)

正确的:

t, ok := i.(string)
if !ok {
  // handle the error gracefully
}

避免Panic

代码在生产模式下必须避免产生panics。panics是连锁故障的主要来源,如果发生错误,函数必须返回错误并允许调用方决定如何处理它。

错误的:

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 <bar>")
    os.Exit(1)
  }
  foo(os.Args[1])
}

正确的:

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 <bar>")
    os.Exit(1)
  }
  if err := foo(os.Args[1]); err != nil {
    panic(err)
  }
}

在大多数情况下,panic/recover不是一种错误处理策略。只有当发生不可恢复的事情(如nil解引用)时,程序才必须死机。

一个例外是程序初始化:程序启动时的错误会导致程序中止,这可能会导致panic。如var _statusTemplate = template.Must(template.New("name").Parse("_statusHTML"))

另一个例外是当包是纯功能的并且没有副作用时。例如,在这种情况下,Hubble中的部分SQL规划使用panic传递进行错误处理。

即使在测试中,也要选择t.Fatal或者t.FailNow而不是panics,以确保测试被标记为失败。

错误的:

// func TestFoo(t *testing.T)

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

正确的:

// func TestFoo(t *testing.T)

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

性能

特定于性能的指导原则仅适用于hot path。

注意strconv比fmt快

当原语与string进行转换时,strconv比fmt快。

错误的:

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

BenchmarkFmtSprint-4 143 ns/op 2 allocs/op

正确的:

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

BenchmarkStrconv-4 64.2 ns/op 1 allocs/op

避免字符串到字节的转换

不要重复地从固定字符串创建byte slices:它会导致堆分配和副本。相反,执行一次转换并捕获结果。

错误的:

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

BenchmarkBad-4 50000000 22.2 ns/op

正确的:

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

BenchmarkGood-4 500000000 3.25 ns/op

代码风格

Line Length

格式化代码,假设它将在100列宽的窗口中读取。将代码包装为100个字符,将注释包装为80个字符,除非这样做会降低代码的可读性。这些值假定tab width为2个字符。

Wrapping Function Signatures

当包装不适合一行的函数声明时,将名称、参数和返回类型放在单独的行上,并在与“func”相同的缩进处加上结束符(这有助于直观地将缩进的参数与缩进的函数体分开)。例子:

func (s *someType) myFunctionName(
arg1 somepackage.SomeArgType, arg2 int, arg3 somepackage.SomeOtherType,
) (somepackage.SomeReturnType, error) {
...
}

如果参数列表过长,一个参数一行:

func (s *someType) myFunctionName(
   arg1 somepackage.SomeArgType,
   arg2 int,
   arg3 somepackage.SomeOtherType,
) (somepackage.SomeReturnType, error) {
...
}

当返回类型需要换行时,遵循相同的规则:

func (s *someType) myFunctionName(
  arg1 somepackage.SomeArgType, arg2 somepackage.SomeOtherType,
) (
  somepackage.SomeReturnType,
  somepackage.SomeOtherType,
  error,
) {
...
}

一个例外是为连续参数省略重复类型时:短参数和相关参数(例如“start,end int64”)应位于同一行,或者该类型应在每一行上重复--任何参数都不应单独出现在没有类型的行上(编辑时易混淆且易碎)。

相似声明分组

Go supports grouping similar declarations.

错误的:

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

正确的:

type Operation int

const (
  Add Operation = iota + 1
  Subtract
  Multiply
)

const ENV_VAR = "MY_ENV"

分组并不限制在什么地方使用,例如,可以在函数内使用

错误的:

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

  ...
}

正确的:

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

  ...
}

导入的分组排序

应该存在两个分组:

  • 基础包
  • 其他

错误的:

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

正确的:

import (
  "fmt"
  "os"

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

Package Names

命名包时,请选择一个名称,即,

  • 全部小写。没有大写或下划线。
  • 大多数调用站点不需要使用命名导入重命名。
  • 简明扼要。请记住,每个呼叫站点都会完整地标识该名称。
  • 不是复数。例如,net/url,而不是net/url。
  • 不是“common”、“util”、“shared”或“lib”。这些都是不好的,没有信息的名字。

参考Package NamesStyle guideline for Go packages

Function Names

我们遵循Go社区使用MixedCaps作为函数名的惯例。测试函数有一个例外,它可能包含下划线,以便对相关的测试用例进行分组,例如TestMyFunction_WhatIsBeingTested。

导入别名

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

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

Function Grouping and Ordering

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

因此,导出的函数应该首先出现在文件中,在struct、const、var定义之后。

newXYZ()/NewXYZ()可能出现在定义类型之后,但在接收器上的其他方法之前。

因为函数是按接收器分组的,所以纯实用函数应该出现在文件的末尾。

错误的:

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

#### 非必要的else

如果在If的两个分支中都设置了变量,则可以用单个If替换它。

错误的:

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

正确的:

a := 10
if b {
  a = 100
}

Top-level Variable Declarations

即顶层,使用标准的var关键字。不要指定类型,除非它与表达式的类型不同。

错误的:

var _s string = F()

func F() string { return "A" }

正确的:

var _s = F()
// Since F already states that it returns a string, we don't need to specify
// the type again.

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.

使用字段名初始化结构

在初始化结构时,几乎总是应该指定字段名。现在这是由go vet强制执行的。

错误的:

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

正确的:

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

异常:当有3个或更少的字段时,可以在测试表中省略字段名。

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

局部变量声明

如果变量被显式设置为某个值,则应使用短变量声明(:=)。

错误的:

var s = "foo"

正确的:

s := "foo"

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

错误的:

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

nil是一个有效的slice

nil是一个长度0的有效切片,这意味着,

  • 不应显式返回长度为零的片段。相反,返回零。
错误的正确的
if x == "" {
    return []int{}
}
if x == "" {
    return nil
}
  • 检查切片是否空,使用len(s) == 0,不要检查nil
错误的正确的
func isEmpty(s []string) bool {
    return s == nil
}
func isEmpty(s []string) bool {
    return len(s) == 0
}
  • 零值(用var声明的slice)在不使用make()的情况下立即可用。

错误的:

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

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

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

正确的:

var nums []int

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

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

缩小变量范围

尽可能缩小变量的范围。如果与reduce嵌套冲突,请不要缩小范围。

错误的:

err := f.Close()
if err != nil {
 return err
}

正确的:

if err := f.Close(); err != nil {
 return err
}

如果需要If之外的函数调用的结果,则不应尝试缩小范围。

错误的:

if f, err := os.Open("f"); err == nil {
  _, err = io.WriteString(f, "data")
  if err != nil {
    return err
  }
  return f.Close()
} else {
  return err
}

正确的:

f, err := os.Open("f")
if err != nil {
   return err
}

if _, err := io.WriteString(f, "data"); err != nil {
  return err
}

return f.Close()

避免裸参数

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

错误的:

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

printInfo("foo", true, true)

正确的:

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

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

更好的是,用自定义类型替换裸bool类型,以获得更可读和类型安全的代码。这允许以后该参数的状态不只是两种(真/假)。

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)

注意:对于“bool”常量,与所有文本一样,注释应该指示参数的名称,而不依赖于参数值。在注释“false”常量时,不要在注释中插入叹号。另外,不要修改注释来否定参数的名称。例如:

func endTxn(commit bool){}
OK:     endTxn(false /* commit */)
NOT OK: endTxn(false /* !commit */)
NOT OK: endTxn(false /* abort */)
// If you want to add an explanation to an argument, a suggested style is to
// include both the param name and the explanation with a dash between them:
OK: endTxn(false /* commit - we abort as we concluded above that we can't commit */)

尽量避免“bool”参数

函数的bool参数通常是不可靠的,因为它们暗示代码的基本内容如下:

func doSomething(shouldDoX bool) {
  if shouldDoX {
    doX()
  } else {
    doY()
  }
}

情况并非总是如此。然而,如果这是对情况的公平评估,则应考虑是否应存在“做其他事”功能。

如果所讨论的“bool”与其他参数一起充当函数的“旋钮”,请考虑将其替换为某种类型的“配置”结构。如果只有一个“bool”参数或情况不太明确,可以考虑用枚举来替换有问题的“bool”。例如:

type EndTxnAction bool

const (
Commit EndTxnAction = false
Abort = true
)

func endTxn(action EndTxnAction) {}
is better than:

func endTxn(commit bool) {}

fmt Verbs

最好用最具体的动词。换言之,尽可能避免%v。但是,当格式化可能为nil且尚未处理nil格式的绑定时,将使用%v。值得注意的是,格式为%s的nil错误将呈现为%!s(<nil>),而格式为%v的nil错误将呈现为<nil>。因此,在格式化未知为非零的错误时,首选%v。

使用原始字符串文字避免转义

Go支持raw string literals,它可以跨越多行并包含引号。使用这些来避免手动转义的字符串,这些字符串很难读取。

错误的:

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

正确的:

wantError := `unknown error:"test"`

初始化结构体引用

初始化结构引用时使用&T{}而不是new(T),以使其与结构体初始化一致。

错误的:

sval := T{Name: "foo"}

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

正确的:

sval := T{Name: "foo"}

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

在Printf外设置字符串格式

如果在字符串文本之外声明Printf样式函数的格式字符串,请使它们成为常量值。

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

错误的:

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

正确的:

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

命名Printf样式函数

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

这意味着您应该尽可能使用预定义的Printf样式函数名。go vet会检查这些默认。有关详细信息,请参见Printf family

如果使用预定义的名称不是一个选项,请用f:Wrapf结束您选择的名称,而不是Wrap。可以要求go vet检查特定的Printf样式名称,但它们必须以f结尾。

go vet -printfuncs=wrapf,statusf

请参考go vet: Printf family check

go实现SQL

在定义语句或虚拟表的结果列标签时,应用以下一般原则:

  • column labels的大小写应一致
  • 不同语句中的同一概念应使用同一个词命名。
  • 例如,“variable”和“value”对应于“SHOW ALL CLUSTER SETTINGS”和“SHOW SESSION ALL”是一致的。
  • 这些标签必须可由周围的查询使用,而不必指定引号。
  • 例如,start_key而不是“Start Key”。另外,避免使用还需要引用的SQL关键字:table_name而不是“table”index_name而不是“index”,等等。永远不要将列命名为user,语法特殊形式user的错误风险太高。改用user_name
  • 使用下划线分隔单词,以与information_schema保持一致。例如,start_key而不是startkey
  • 避免使用缩写,除非英语口语中的大多数单词已经使用缩写。例如, ididentifier可以, 但loclocation不行.
  • 对于类似于“主键”的列(标识其余列所描述的对象),必须在标签中消除其含义高度重载的单词的歧义。例如,zone_idjob_idtable_id而不是到处都是'id'。table_namecolumn_name等,而不是name
  • 对于可以由两种或两种以上类型的句柄(如按ID或按名称)引用的数据库对象,列标签必须消除正在报告的句柄类型的歧义。这使得以后可以在其他列中报告其他句柄。例如,table_name而不是table,以便以后可以添加table_id
  • 复制“information_schema”表或先前的“SHOW”语句中已存在的数据的标签应与“information_schema”表或“SHOW”语句使用相同的标签,前提是它已符合上述原则。

Patterns

Data-driven tests

我们通过数据驱动测试包为hubble中的表驱动测试(见下一节)提供了一种替代方法。

package datadriven

// RunTest invokes a data-driven test. The test cases are contained in a
// separate test file and are dynamically loaded, parsed, and executed by this
// testing framework. By convention, test files are typically located in a
// sub-directory called "testdata". Each test file has the following format:
//
//   <command>[,<command>...] [arg | arg=val | arg=(val1, val2, ...)]...
//   <input to the command>
//   ----
//   <expected results>
//
// The command input can contain blank lines. However, by default, the expected
// results cannot contain blank lines. This alternate syntax allows the use of
// blank lines:
//
//   <command>[,<command>...] [arg | arg=val | arg=(val1, val2, ...)]...
//   <input to the command>
//   ----
//   ----
//   <expected results>
//
//   <more expected results>
//   ----
//   ----
//
// To execute data-driven tests, pass the path of the test file as well as a
// function which can interpret and execute whatever commands are present in
// the test file. The framework invokes the function, passing it information
// about the test case in a TestData struct. The function then returns the
// actual results of the case, which this function compares with the expected
// results, and either succeeds or fails the test.
func RunTest(t *testing.T, path string, f func(d *TestData) string) 

Test Tables

对子测试使用表驱动测试,以避免在核心测试逻辑重复时重复代码。

错误的:

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

正确的:

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

测试表使向错误消息添加上下文、减少重复逻辑和添加新测试用例变得更容易。

我们遵循这样的约定:结构的片段被称为测试和每个测试用例tt。此外,我们鼓励使用give和want前缀解释每个测试用例的输入和输出值。

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

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

Functional Options

函数选项是一种模式,在这种模式中,您可以声明一个不透明的选项类型,该类型在某些内部结构中记录信息。您接受这些选项的可变数目,并根据选项在内部结构上记录的完整信息进行操作。

将此模式用于构造函数和其他需要扩展的公共api中的可选参数,特别是在这些函数上已经有三个或更多参数的情况下。

错误的:

// package db

func Connect(
  addr string,
  timeout time.Duration,
  caching bool,
) (*Connection, error) {
  // ...
}

// Timeout and caching must always be provided,
// even if the user wants to use the default.

db.Connect(addr, db.DefaultTimeout, db.DefaultCaching)
db.Connect(addr, newTimeout, db.DefaultCaching)
db.Connect(addr, db.DefaultTimeout, false /* caching */)
db.Connect(addr, newTimeout, false /* caching */)

正确的:

type options struct {
  timeout time.Duration
  caching bool
}

// Option overrides behavior of Connect.
type Option interface {
  apply(*options)
}

type optionFunc func(*options)

func (f optionFunc) apply(o *options) {
  f(o)
}

func WithTimeout(t time.Duration) Option {
  return optionFunc(func(o *options) {
    o.timeout = t
  })
}

func WithCaching(cache bool) Option {
  return optionFunc(func(o *options) {
    o.caching = cache
  })
}

// Connect creates a connection.
func Connect(
  addr string,
  opts ...Option,
) (*Connection, error) {
  options := options{
    timeout: defaultTimeout,
    caching: defaultCaching,
  }

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

  // ...
}

// Options must be provided only if needed.

db.Connect(addr)
db.Connect(addr, db.WithTimeout(newTimeout))
db.Connect(addr, db.WithCaching(false))
db.Connect(
  addr,
  db.WithCaching(false),
  db.WithTimeout(newTimeout),
)

参考下面关于函数选项的文档Functional options for friendly APIs