Uber 的 Go 規(guī)范

性能

性能方面的指導(dǎo)準(zhǔn)則只適用于高頻調(diào)用場景。

使用 strconv 而不是 fmt

當(dāng)需要原始類型和字符串互相轉(zhuǎn)化時，strconv比fmt性能更好。

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

避免 字符串到字節(jié)的轉(zhuǎn)化

不要在for循環(huán)中創(chuàng)建[]byte類型，應(yīng)該在for循環(huán)開始前把[]byte數(shù)據(jù)準(zhǔn)備好。

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

預(yù)先指定容器類型的容量

盡可能指定容器類型變量的容量來預(yù)先分配容器類型所需的內(nèi)存大小。這樣可以預(yù)防由于后續(xù)由分配元素 （由于拷貝或重新指定容器大?。┒鴮?dǎo)致的內(nèi)存分配。

指定Map容量

如果有可能，用make來初始化map類型，并指定map的大小。

make(map[T1]T2, hint)

使用 make() 初始化map時，提供一個容量來執(zhí)行size，這樣會減少后續(xù)將給map添加元素時引起的內(nèi)存分配。

注意，和 slice 不同，給map指定容量不意味著搶占式內(nèi)存分配完成，而是會用于預(yù)估的哈希表內(nèi)部 buckets。因此，當(dāng)你給 map 添加元素，或者給 map 指定值時，仍有可能發(fā)生內(nèi)存分配。

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
}

指定Slice容量

如果有可能的話，在使用make()初始化slice的時候提供容量大小，尤其是后面需要 append 操作時。

make([]T, length, capacity)

和 map 不同，slice的容量不是一個提示：編譯器會根據(jù) make() 提供的容量信息申請足夠的內(nèi)存， 這意味著后續(xù)的 append() 操作不會申請內(nèi)存（除非slice的長度和容量相等，這樣的話后續(xù)添加元素 會申請內(nèi)存來調(diào)整 slice 的大?。?。

for n := 0; n < b.N; n++ {
  data := make([]int, 0)
  for k := 0; k < size; k++{
    data = append(data, k)
  }
}

for n := 0; n < b.N; n++ {
  data := make([]int, 0, size)
  for k := 0; k < size; k++{
    data = append(data, k)
  }
}

BenchmarkBad-4    100000000    2.48s

BenchmarkGood-4   100000000    0.21s

規(guī)范

避免代碼過長

避免由于長度過長而需要水平滾動或者太需要轉(zhuǎn)動頭部的代碼。

我們建議一行代碼長度為 99個字符，如果代碼超過了這個限制就應(yīng)該換行。但是這也不是絕對的，代碼 可以超過這個限制。

一致性

本文的一些指導(dǎo)準(zhǔn)則可以被客觀評估，其他準(zhǔn)則可以根據(jù)實(shí)際情況進(jìn)行選擇。

但是最重要是，在你的代碼中要保持一致。

一致性的代碼更易于維護(hù)，更容易合理化，需要的認(rèn)知開銷較少；當(dāng)新的管理出現(xiàn)時或 bug 被修復(fù)后也更易于 遷移和更新。

與之相反，如果單個代碼庫中有多種沖突的風(fēng)格，會讓維護(hù)成本升高、不確定性增高、認(rèn)知不協(xié)調(diào)，這些問題會 導(dǎo)致開發(fā)效率降低，code review 困難，且容易產(chǎn)生 bug。

當(dāng)你在代碼庫中實(shí)施標(biāo)準(zhǔn)時，建議最低在包層面進(jìn)行修改：在子包層面進(jìn)行應(yīng)用違反了上述約定，因?yàn)樵谝环N代碼 里面引入了多種風(fēng)格。

相似聲明放一組

Go語言支持組引用。

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
)

注意只把相關(guān)的變量聲明到一個組里，不想管的聲明放在多個組里。

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"

組聲明不限制在哪使用。比如，你可以在函數(shù)中使用組聲明。

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

  // ...
}

例外：對于變量聲明，尤其是函數(shù)中的變量聲明，不管他們之間是否有關(guān)系，都應(yīng)該被放在一個組內(nèi)。

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
  )

  // ...
}

包導(dǎo)入順序

包中應(yīng)該有兩種導(dǎo)入順序：

• 標(biāo)準(zhǔn)庫
• 其他庫

默認(rèn)情況下，應(yīng)該使用 goimports 的導(dǎo)入順序。

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

import (
  "fmt"
  "os"

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

包命名

當(dāng)命名包時，應(yīng)按照下面原則命名：

• 全小寫字母。無大寫字母或下劃線。
• 大多數(shù)導(dǎo)入包的情況下，不需要對包重新命名。
• 簡短而簡潔，因?yàn)楫?dāng)你使用包名時你都需要完成輸入包名稱。
• 不要使用復(fù)數(shù)。比如：命名為 net/url, 而不是 net/urls。
• 不要使用"common", "util", "shared", 或 "lib"。這些包含有信息太少了。

可以參考 Package Names 和 Style guideline for Go packages.

函數(shù)命名

我們遵守 Go 社區(qū) MixedCaps for function names 約定。一種其他情況是使用測試函數(shù)。測試函數(shù) 命名可以包含下劃線以便于相關(guān)測試函數(shù)進(jìn)行分組。比如：TestMyFunction_WhatIsBeingTested。

導(dǎo)入別名

如果包名稱和導(dǎo)入路徑最后一個元素不匹配，就需要使用導(dǎo)入別名。

import (
  "net/http"

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

其他情況下，除非幾個包之間有導(dǎo)入沖突，否則應(yīng)該避免使用導(dǎo)入別名。

import (
  "fmt"
  "os"


  nettrace "golang.net/x/trace"
)

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

  nettrace "golang.net/x/trace"
)

函數(shù)分組和排序

• 函數(shù)應(yīng)該按照大概調(diào)用順序排序。
• 一個文件中的函數(shù)應(yīng)該按照接收者分組。

因此，導(dǎo)入的函數(shù)時，應(yīng)該放在 struct, const, var 的下面。

像 newXYZ()/NewXYZ() 這樣的函數(shù)可能會出現(xiàn)在類型定義下、接收者的其他方法之上。

由于函數(shù)是按照接收者進(jìn)行分組的，普通的工具函數(shù)應(yīng)該放在文件末尾。

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

減少嵌套

代碼應(yīng)通過盡早處理錯誤/特殊情況盡早處理/循環(huán)中使用 continue 等手段，來減少嵌套代碼過多問題。

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

如啊a變量在兩個if分支中都進(jìn)行賦值操作，則可以被替換為只在一個if分支中聲明。

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

a := 10
if b {
  a = 100
}

頂層變量聲明

在頂層使用var來聲明變量。不要指定類型，除非它和表達(dá)式的類型不同。

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

如果表達(dá)式的類型和所需類型不一樣，需要指定類型。

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.

非導(dǎo)出變量使用_前綴

對于非導(dǎo)出類型的變量，在用vars and const聲明時加上_前綴，來表示他們是全局符號。

原因：頂層聲明的變量作用域一般是包范圍。用一個常見的名字可能會導(dǎo)致在其他包中被意外修改。

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

// foo.go

const (
  _defaultPort = 8080
  _defaultUser = "user"
)

異常：非導(dǎo)出的錯誤類型一般使用不帶 _ 的 err 前綴。參考Error Naming.

結(jié)構(gòu)體內(nèi)嵌類型

嵌入類型應(yīng)該放在結(jié)構(gòu)體的最上面，應(yīng)該和結(jié)構(gòu)體的常規(guī)字段用一個空行分隔開。

type Client struct {
  version int
  http.Client
}

type Client struct {
  http.Client

  version int
}

內(nèi)嵌類型會帶來足夠的好處，比如在語義上會增加或增強(qiáng)功能。但應(yīng)該在對用戶沒有影響的情況下使用內(nèi)嵌。(參考: 避免在公共結(jié)構(gòu)中嵌入類型).

例外：即使是未導(dǎo)出類型，Mutex 也不應(yīng)該被內(nèi)嵌。參考：: Mutex的零值是有效的.

這些情況下避免內(nèi)嵌:

• 單純?yōu)榱吮憷兔烙^。
• 讓外部類型構(gòu)造起來或使用起來更困難。
• 影響了外部的零值。如果外部類型的零值是有用的，嵌入類型應(yīng)該也有一個有用的零值。
• 作為嵌入類型的副作用，公開外部類型的不相關(guān)函數(shù)或字段。
• 公開非導(dǎo)出類型。
• 影響外部類型的復(fù)制語義。
• 影響外部類型的API或類型語義。
• 影響內(nèi)部類型的非規(guī)范形式。
• 公開外部類型的詳細(xì)實(shí)現(xiàn)信息。
• 允許用戶觀察和控制內(nèi)部類型。
• 通過包裝的形式改變了內(nèi)部函數(shù)的行為，這種包裝的方式會給用戶造成意外觀感。

簡單概括，使用嵌入類型時要明確目的。一個不錯的方式是："這些嵌入的字段/方法是否需要被直接添加到外部 類型"，如果答案是"一些"或者"No"，不要使用內(nèi)嵌類型，而是使用命名字段。

type A struct {
    // Bad: A.Lock() and A.Unlock() are
    //      now available, provide no
    //      functional benefit, and allow
    //      users to control details about
    //      the internals of A.
    sync.Mutex
}

type countingWriteCloser struct {
    // Good: Write() is provided at this
    //       outer layer for a specific
    //       purpose, and delegates work
    //       to the inner type's Write().
    io.WriteCloser

    count int
}

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

type Book struct {
    // Bad: pointer changes zero value usefulness
    io.ReadWriter

    // other fields
}

// later

var b Book
b.Read(...)  // panic: nil pointer
b.String()   // panic: nil pointer
b.Write(...) // panic: nil pointer

type Book struct {
    // Good: has useful zero value
    bytes.Buffer

    // other fields
}

// later

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

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
}

本地變量聲明

如果將變量聲明為某個值，應(yīng)該使用短變量命名方式：:=。

var s = "foo"

s := "foo"

然而，有些情況下用 var 會讓聲明語句更加清晰，比如聲明空slice.

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的有效slice, 意味著：

• 你不應(yīng)該聲明一個長度為0的空slice，而是用nil來代替。

  Bad	Good
  if x == "" {   return []int{} }	if x == "" {   return nil }

• 要檢查slice是否為空，不應(yīng)該檢查 nil, 而是用長度判斷len(s) == 0。

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

• 用 var 聲明的零值slice是有效的，沒必要用 make 來創(chuàng)建。

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

另外記住，雖然 nil 的slice有效，但是它不等于長度為0的 slice。在一些情況下(比如說序列化)， 這兩種slice的表現(xiàn)不同。

縮小變量作用域

盡可能減小變量的作用域。如果與 減少嵌套 沖突，就不要縮小。

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

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

但是如果作用域是 if 范圍之外，不應(yīng)該減少作用域。

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

不面參數(shù)語義不明確

在函數(shù)中裸傳參數(shù)值會讓代碼語義不明確，可以添加 C 風(fēng)格(/* ... */)的注釋。

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

printInfo("foo", true, true)

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

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

當(dāng)然，更好的處理方式將上面的 bool 換成自定義類型。因?yàn)槲磥砜赡懿粌H僅局限于兩個bool值(true/false)。

type Region int

const (
  UnknownRegion Region = iota
  Local
)

type Status int

const (
  StatusReady Status = iota + 1
  StatusDone
  // 獲取未來會有 StatusInProgress 枚舉
)

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

字符串中避免轉(zhuǎn)義

Go中支持 字符串原始值,當(dāng)需要 轉(zhuǎn)義時，盡量使用 "`" 來包裝字符串。

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

wantError := `unknown error:"test"`

初始化結(jié)構(gòu)體

初始化結(jié)構(gòu)體時聲明字段名

在你初始化結(jié)構(gòu)時，幾乎應(yīng)該始終指定字段名。目前由go vet強(qiáng)制執(zhí)行。

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

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

例外：當(dāng)有 3 個或更少的字段時，測試表中的字段名也許可以省略。

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

省略結(jié)構(gòu)體中的零值字段

當(dāng)初始化結(jié)構(gòu)體字段時，除非需要提供一個有意義的上下文，否則需要忽略對零值字段進(jìn)行賦值。因?yàn)镚o 會自動給這些零值字段進(jìn)行填充。

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

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

這種行為讓我們忽略了上下文無關(guān)的噪音信息。只關(guān)注有意義的特殊值。

當(dāng)零值代表有意義的上下文時需要提供零值。比如在  表驅(qū)動測試 中零值字段 是有意義的。

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

空結(jié)構(gòu)體用var聲明

當(dāng)結(jié)構(gòu)體中所有的字段都為空時，用 var 來聲明結(jié)構(gòu)體。

user := User{}

var user User

這種 零值結(jié)構(gòu)體 和具有非零值字段的結(jié)構(gòu)體有所不同，和 map初始化 更相似， 和我們更想用的 [聲明空Slices][聲明空Slices] 更匹配。

初始化結(jié)構(gòu)體引用

初始化結(jié)構(gòu)引用時，請使用&T{}代替new(T)，以使其與結(jié)構(gòu)體初始化一致。

sval := T{Name: "foo"}

// 非一致的
sptr := new(T)
sptr.Name = "bar"

sval := T{Name: "foo"}

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

初始化Map

優(yōu)先使用make來創(chuàng)建空map，這樣使得map的初始化不同于聲明，而且你還可以在 make 中添加map的大小提示。

var (
  // m1 的讀寫操作都是安全的
  // m2 的寫操作會panic
  m1 = map[T1]T2{}
  m2 map[T1]T2
)

var (
  // m1 的讀寫操作都是安全的
  // m2 的寫操作會panic
  m1 = make(map[T1]T2)
  m2 map[T1]T2
)

盡可能在 make() 中制定map的初始化容量，可以參考：Specifying Map Capacity Hints。

另外，如果map初始化的時候需要賦值固定信息，使用 map literals 方式來初始化。

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

原則上：在初始化map時增加一組固定的元素，就使用map literals。否則就使用 make(如果可以， 盡可能指定map的容量)。

在Printf外面格式化字符串

如果你在函數(shù)外聲明 Printf 風(fēng)格 函數(shù)的格式字符串，請將其設(shè)置為 const 常量。

這有助于go vet對格式字符串執(zhí)行靜態(tài)分析。

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

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

命名Printf樣式函數(shù)

使用Printf函數(shù)時，應(yīng)保證go vet可以檢測到他的格式化字符串。

這意味著你需要使用預(yù)定義的Printf函數(shù)名稱，go vet會默認(rèn)檢查這些。更多信息，請參考：Printf family

如果不能使用預(yù)定義的名稱，請以 f 結(jié)束選擇的名稱：Wrapf，而不是Wrap。go vet可以要求檢查特定的 Printf樣式名稱，但名稱必須以f結(jié)尾。

$ go vet -printfuncs=wrapf,statusf

參考 go vet: Printf family check.

Patterns

Test Tables

當(dāng)你的測試用例形式上重復(fù)時，用 subtests 方式編寫case會讓測試用例看起來更加簡潔。

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

顯然，如果你用了test table的方式，在拓展測試用例時也會顯得更加清晰。

我們遵守這樣的準(zhǔn)則：搞一個slice類型的struct測試用例，每個測試case叫做tt。然后使用give和want說明測試用例的輸入和輸出。

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

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

對于并行測試，比如一些特殊的循環(huán) (比如那些生產(chǎn) goroutine 或 在循環(huán)中捕獲引用的循環(huán)), 需要 注意在循環(huán)中明確分配循環(huán)變量來確保不會產(chǎn)生閉包。

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

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

在上面的例子中，由于循環(huán)中使用了 t.Parallel()，我們必須在外部循環(huán)中聲明一個 tt 變量。如果不這么做，大多數(shù)測試用例都會收到一個非預(yù)期的 tt，或是一個在運(yùn)行期改變的值。

函數(shù)功能選項(xiàng)API

功能選項(xiàng)是一種模式，你可以聲明一個對用戶不透明的 Option 類型，在一些內(nèi)部結(jié)構(gòu)中記錄信息。函數(shù)接收不定長的參數(shù)選項(xiàng)，并根據(jù)參數(shù)做不同的行為。

對于需要拓展參數(shù)的構(gòu)造方法或是其他需要可選參數(shù)的公共API可以考慮這種模式，對于參數(shù)在三個及以上 的函數(shù)更應(yīng)該考慮。

// package db

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

// package db

type Option interface {
  // ...
}

func WithCache(c bool) Option {
  // ...
}

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

// Open 創(chuàng)建一個連接
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 /* cache */, zap.NewNop())
db.Open(addr, false /* cache */, 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),
)

我們建議這種模式的實(shí)現(xiàn)方式是 提供一個 Option 接口，里面有一個非導(dǎo)出類型方法，在一個非 導(dǎo)出類型的 options 結(jié)構(gòu)體中記錄選項(xiàng)。

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

// Open 創(chuàng)建一個連接
func Open(
  addr string,
  opts ...Option,
) (*Connection, error) {
  options := options{
    cache:  defaultCache,
    logger: zap.NewNop(),
  }

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

  // ...
}

還有一種用閉包實(shí)現(xiàn)這種方法的模式，但我們認(rèn)為上面提供的這種模式給作者提供了更高的靈活性，更 易于調(diào)試和測試。這種方式可以在測試和mock中進(jìn)行比較，而閉包方式難以做到。此外，它允許 option 實(shí)現(xiàn)其他接口，比如 fmt.Stringer，會 string 類型的可讀性更高。

還可以參考：

• Self-referential functions and the design of options

• Functional options for friendly APIs

Linting

比其他任何 "神圣" linter 工具更重要的是，在你的代碼庫里使用一致性的 lint 工具。

我們建議最少要使用下面這些 linters 工具嗎，因?yàn)槲覀冋J(rèn)為這些工具可以幫你捕獲最常見的問題，有助于 在沒有規(guī)定的前提下提高代碼質(zhì)量：

• errcheck 確保錯誤被處理

• goimports 格式化代碼和管理包引用

• golint 指出常見的文本錯誤

• govet 分析代碼中的常見錯誤

• staticcheck 各種靜態(tài)分析檢查

Lint Runners

由于優(yōu)秀的性能表現(xiàn)，我們推薦 golangci-lint 作為Go代碼的首選 lint 工具。這個倉庫有在一個.golangci.yml 例子，里面有配置的 linters 工具和設(shè)置。

golangci-lint 有一系列 various linters 可供使用。建議將這些 linters 作為基礎(chǔ)集合， 我們鼓勵團(tuán)隊(duì)內(nèi)部將其他有意義的 linters 工具在他們的項(xiàng)目中進(jìn)行使用。