Uber 的 Go 規(guī)范

Uber公司推出的Go語言規(guī)范，建議沒看過的同學(xué)看一遍，里面的規(guī)范很多，不見得每一條都采納，不現(xiàn)實(shí)，選一些適合的可以落地執(zhí)行的拿來參考就行。

介紹

本指南的目的是通過詳細(xì)描述在Uber編寫Go代碼的注意事項(xiàng)來管理這種復(fù)雜性。這些規(guī)則的存在是為了保持代碼庫的可管理性，同時(shí)還允許工程師有效地使用Go語言的特性。

本指南最初是由Prashant Varanasi和Simon Newton創(chuàng)建的，是為了讓一些同事盡快掌握Go的使用方法。多年來，我們根據(jù)其他人的反饋對(duì)它進(jìn)行了修改。

這記錄了我們?cè)?Uber 所遵循的 Go 代碼中的習(xí)慣性約定。其中很多是Go里面的一般準(zhǔn)則，而其他的則是根據(jù)外部資源進(jìn)行擴(kuò)展：

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

我們的目標(biāo)是使代碼樣本準(zhǔn)確地適用于Go的兩個(gè)最新的次要版本。

所有代碼在通過golint和go vet運(yùn)行時(shí)應(yīng)該是沒有錯(cuò)誤的。我們建議將您的編輯器設(shè)置為：

• 保存時(shí)運(yùn)行 goimports
• 運(yùn)行 golint 和 go vet 檢查錯(cuò)誤

你可以在這里找到編輯器支持Go工具的信息：https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins

指南

指向interface的指針

你幾乎不需要一個(gè)指向 interface 的指針，interface類型數(shù)據(jù)應(yīng)該直接傳遞，但實(shí)際上 interface 底層是一個(gè)指針。

interface 類型包括兩部分：

1. 一個(gè)指向特定類型的指針?？梢詫⑵湟暈?"類型"。
2. 數(shù)據(jù)指針。如果底層數(shù)據(jù)是指針，會(huì)被直接存儲(chǔ)。如果底層數(shù)據(jù)是值，那會(huì)存儲(chǔ)這個(gè)數(shù)據(jù)的指針。

如果你想要接口方法修改基礎(chǔ)數(shù)據(jù)，那必須使用指針。

驗(yàn)證接口合法性

在編譯期驗(yàn)證接口的合法性，需要驗(yàn)證的有：

• 驗(yàn)證導(dǎo)出類型在作為API時(shí)是否實(shí)現(xiàn)了特定接口
• 實(shí)現(xiàn)一個(gè)接口的導(dǎo)出和非導(dǎo)出類型是集合的一部分
• 違反接口合理性無法編譯通過，通知用戶

type Handler struct {
  // ...
}



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

type Handler struct {
  // ...
}

var _ http.Handler = (*Handler)(nil)

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

如果*Handler沒有實(shí)現(xiàn)http.Handler接口，那么var _ http.Handler = (*Handler)(nil)語句在編譯期就會(huì)報(bào)錯(cuò)；

賦值語句的右邊部門應(yīng)是斷言類型的零值。對(duì)于指針類型(像*Handler)、slice和map類型，零值為nil,對(duì)于結(jié)構(gòu)體類型，零值為空結(jié)構(gòu)體，下面是空結(jié)構(gòu)體的例子。

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

// LogHandler{}是空結(jié)構(gòu)體
var _ http.Handler = LogHandler{}

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

接收者和接口

使用 值類型 接收者的方法既可以通過值調(diào)用，也可以通過指針調(diào)用。

使用 指針類型 接收者的方法只能通過指針或者 addressable values調(diào)用。

例如：

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

// 值類型可以調(diào)用Read()
sVals[1].Read()

// 值類型調(diào)用Write方法會(huì)報(bào)編譯錯(cuò)誤
//  sVals[1].Write("test")

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

// 指針類型 Read 和 Write 方法都可以調(diào)用
sPtrs[1].Read()
sPtrs[1].Write("test")

同樣的，接口可以通過指針調(diào)用，即使這個(gè)方法的接收者是指類型。

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

// 這個(gè)例子編譯會(huì)報(bào)錯(cuò)，因?yàn)閟2Val是值類型，而S2的方法里接收者是指針類型.
//   i = s2Val

Effective Go 有一段關(guān)于 Pointers vs. Values 的優(yōu)秀講解

Mutexes的零值是有效的

sync.Mutex 和 sync.RWMutex 的零值是有效的，所以不需要實(shí)例化一個(gè)Mutex的指針。

mu := new(sync.Mutex)
mu.Lock()

var mu sync.Mutex
mu.Lock()

如果結(jié)構(gòu)體中包含mutex，在使用結(jié)構(gòu)體的指針時(shí)，mutex應(yīng)該是結(jié)構(gòu)體的非指針字段，也不要把mutex內(nèi)嵌到結(jié)構(gòu)體中，即使結(jié)構(gòu)體是非導(dǎo)出類型。

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

在邊界拷貝Slices和Maps

slice 和 map 類型包含指向data數(shù)據(jù)的指針，所以當(dāng)你需要復(fù)制時(shí)應(yīng)格外注意。

接收 Slices 和 Maps

如果在函數(shù)調(diào)用中傳遞 map 或 slice, 請(qǐng)記住這個(gè)函數(shù)可以修改它。

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

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

// 這樣賦值會(huì)影響到 d1.trips
trips[0] = ...

func (d *Driver) SetTrips(trips []Trip) {
  d.trips = make([]Trip, len(trips))
  copy(d.trips, trips)
}

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

// 這樣賦值不會(huì)影響 d1.trips(因?yàn)?nbsp;SetTrips 內(nèi)部有copy).
trips[0] = ...

返回 Slices 和 Maps

同樣，請(qǐng)注意用戶對(duì) maps 或 slices 的修改暴露了內(nèi)部狀態(tài)。

type Stats struct {
  mu sync.Mutex
  counters map[string]int
}

// Snapshot 返回當(dāng)前的 stats.
func (s *Stats) Snapshot() map[string]int {
  s.mu.Lock()
  defer s.mu.Unlock()

  return s.counters
}

// snapshot 變量不在受 mutex鎖保護(hù)，任何對(duì) snapshot 的訪問會(huì)受數(shù)據(jù)竟態(tài)的影響
snapshot := stats.Snapshot()

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 現(xiàn)在只是個(gè)copy。
snapshot := stats.Snapshot()

使用Defer釋放資源

在讀寫文件、使用鎖時(shí)，使用 defer 釋放資源

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

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

return newCount

// 當(dāng)有多分支 return 時(shí)，很容易漏寫Unlock().

p.Lock()
defer p.Unlock()

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

p.count++
return p.count

// 使用defer在一個(gè)地方 Unlock, 代碼可讀性更好

調(diào)用 defer 的性能開銷非常小，但如果你需要納秒級(jí)別的函數(shù)調(diào)用，那可能需要避免使用 defer。使用 defer 帶來的可讀性 勝過引入其它帶來的性能開銷。defer 尤其適用于適用于那些不僅是內(nèi)存 放在的行數(shù)較多、邏輯較為復(fù)雜的大方法，這些方法中其他代碼邏輯的執(zhí)行成本比 defer 執(zhí)行成本更大。

Channel 大小應(yīng)為 0 或 1

Channels 的大小應(yīng)該是1或無緩沖的。默認(rèn)情況下，channels 是無緩沖的，size為0。其他size需經(jīng)過嚴(yán)格的審查?？紤] channel 的size 是如何定義的，是什么造成了 channel 在負(fù)荷情況下被寫滿而無法寫入，以及無法寫入會(huì)發(fā)生什么。

// 這個(gè) size 對(duì)任何操作都?jí)蛄耍?/span>
c := make(chan int, 64)

// Size 是1
c := make(chan int, 1) // or
// 無緩沖 channel
c := make(chan int)

枚舉類型值從1開始

在Go中聲明枚舉值的標(biāo)準(zhǔn)方法是使用const包iota。由于變量的默認(rèn)值為0，因此枚舉類型的值需要從1開始。

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

當(dāng)你需要將0值視為默認(rèn)行為時(shí)，枚舉類型從0開始是有意義的。

type LogOutput int

const (
  LogToStdout LogOutput = iota
  LogToFile
  LogToRemote
)

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

使用time包來處理時(shí)間

時(shí)間處理很復(fù)雜，關(guān)于時(shí)間錯(cuò)誤預(yù)估有以下這些點(diǎn)。

1. 一天有24小時(shí)
2. 一小時(shí)有60分鐘
3. 一周有7天
4. 一年有365天
5. 其他易錯(cuò)點(diǎn)

舉例來說, 1 表示在一個(gè)時(shí)間點(diǎn)加上24小時(shí)并不一定會(huì)產(chǎn)生新的一天。

因此，在處理時(shí)間時(shí)應(yīng)始終使用"time"包，因?yàn)樗鼤?huì)用更安全、準(zhǔn)確的方式來處理這些不正確的假設(shè)。

用 time.Time 表示瞬時(shí)時(shí)間

需要瞬時(shí)時(shí)間語義時(shí)，使用time.Time ，在進(jìn)行比較、增加或減少時(shí)間段時(shí)，使用time.Time包里的方法。

func isActive(now, start, stop int) bool {
  return start <= now && now < stop
}

func isActive(now, start, stop time.Time) bool {
  return (start.Before(now) || start.Equal(now)) && now.Before(stop)
}

用 time.Duration 表示時(shí)間段

應(yīng)使用 time.Duration 來表示時(shí)間段

func poll(delay int) {
  for {
    // ...
    time.Sleep(time.Duration(delay) * time.Millisecond)
  }
}

poll(10) // 這里單位是秒還是毫秒

func poll(delay time.Duration) { // 使用 time.Duration 表示時(shí)間段
  for {
    // ...
    time.Sleep(delay)
  }
}

poll(10*time.Second) // 明確單位

回到剛剛的例子，在一個(gè)瞬時(shí)時(shí)間加上24小時(shí)，怎么加這個(gè) "24小時(shí)" 取決于我們的意圖。如果我們想獲取 下一天的當(dāng)前時(shí)間，我們應(yīng)該使用 Time.AddDate。如果我們想獲取比當(dāng)前時(shí)間晚24小時(shí)的瞬時(shí)時(shí)間， 我們應(yīng)該應(yīng)該使用 Time.Add。

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

對(duì)外交互 使用 time.Time 和 time.Duration

在對(duì)外交互時(shí)盡可能使用 time.Duration 和 time.Time，例如：

• Command-line 標(biāo)記: flag 通過支持 time.ParseDuration 來支持 time.Duration
• JSON: encoding/json 通過  [UnmarshalJSON 方法] 支持把 time.Time 解碼為 RFC 3339 字符串
• SQL: database/sql 支持把 DATETIME 或 TIMESTAMP 類型轉(zhuǎn)化為 time.Time
• YAML: gopkg.in/yaml.v2 支持把 time.Time 作為一個(gè) RFC 3339 字符串, 通過支持time.ParseDuration 來支持time.Duration。

如果交互中不支持使用time.Duration，那字段名中應(yīng)包含單位，類型應(yīng)為int或float64。

例如, 由于 encoding/json 不支持 time.Duration 類型, 因此字段名中應(yīng)包含時(shí)間單位。

// {"interval": 2}
type Config struct {
  Interval int `json:"interval"`
}

// {"intervalMillis": 2000}
type Config struct { // Millis 是單位
  IntervalMillis int `json:"intervalMillis"`
}

如果在交互中不能使用 time.Time，除非有額外約定，否則應(yīng)該使用 string 和 RFC 3339定義的 時(shí)間戳格式。默認(rèn)情況下， Time.UnmarshalText 使用這種格式，并可以通過time.RFC3339在Time.Format 和 time.Parse 中使用。

盡管在實(shí)踐中這不是什么問題，但是你需要記住"time"不能解析閏秒時(shí)間戳(8728),在計(jì)算中也不考慮閏秒(15190)。因此如果你要比較兩個(gè)瞬時(shí)時(shí)間，比較結(jié)果不會(huì)包含這兩個(gè)瞬時(shí)時(shí)間可能會(huì)出現(xiàn)的閏秒。

錯(cuò)誤

錯(cuò)誤類型

聲明錯(cuò)誤的選項(xiàng)很少。在為你的代碼選擇合適的用例之前，考慮這些事項(xiàng)：

• 調(diào)用方需要匹配錯(cuò)誤嗎，還是調(diào)用方需要自己處理錯(cuò)誤。如果需要匹配錯(cuò)誤，那應(yīng)該聲明頂級(jí) 錯(cuò)誤類型或自定義類型 來讓 errors.Is 或 errors.As 匹配。
• 錯(cuò)誤信息是靜態(tài)字符串嗎，還是說錯(cuò)誤信息是需要上下文的動(dòng)態(tài)字符串。如果是靜態(tài)字符串， 我們可以使用 errors.New，如果是動(dòng)態(tài)字符串，我們應(yīng)該使用fmt.Errorf來 自定義錯(cuò)誤類型。
• 我們是否正在傳遞由下游返回的新的錯(cuò)誤類型，如果是這樣，參考section on error wrapping.

舉例，使用 errors.New 表示一個(gè)靜態(tài)字符串錯(cuò)誤。如果調(diào)用方需要匹配并處理這個(gè)錯(cuò)誤， 就把這個(gè)錯(cuò)誤聲明為變量來支持和 errors.Is 匹配。

// package foo

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

// package bar

if err := foo.Open(); err != nil {
  //無法處理錯(cuò)誤
  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) {
    // 處理這個(gè)錯(cuò)誤
  } else {
    panic("unknown error")
  }
}

對(duì)于動(dòng)態(tài)字符串的錯(cuò)誤，如果調(diào)用方不需要匹配就是用fmt.Errorf，需要匹配就搞一個(gè)自定義error。

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

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

注意，如果你的包里導(dǎo)出了錯(cuò)誤變量或錯(cuò)誤類型，那這個(gè)錯(cuò)誤將變成你包里公共API的一部分。

錯(cuò)誤包裝

調(diào)用函數(shù)失敗時(shí)，有三種選擇供你選擇：

• 返回原始錯(cuò)誤
• 用 fmt.Errorf 和 %w 包裝上下文信息
• 用 fmt.Errorf 和 %v 包裝上下文信息

返回原始錯(cuò)誤不會(huì)附加上下文信息，這樣就保持了原始錯(cuò)誤類型和信息。比較適用于lib庫類型代碼 展示底層錯(cuò)誤信息。

如果不是lib庫，就需要增加所需的上下文信息，不然就會(huì)出現(xiàn) "connection refused" 這樣非常 模糊的錯(cuò)誤，理論上應(yīng)該添加上下文，來得到這樣的報(bào)錯(cuò)信息："call service foo: connection refused"。

在錯(cuò)誤類型上使用 fmt.Errorf 來添加上下文信息，根據(jù)調(diào)用方不同的使用方式，可以選擇 %w 或 %v 動(dòng)詞。

• 如果調(diào)用方需要訪問底層錯(cuò)誤，使用%w動(dòng)詞，這是一個(gè)用來包裝錯(cuò)誤的動(dòng)詞，如果你在代碼中使用到了它，請(qǐng)注意 調(diào)用方會(huì)對(duì)此產(chǎn)生依賴，所以當(dāng)你的包裝的錯(cuò)誤是用var聲明的已知類型，需要在你的代碼里對(duì)其進(jìn)行測(cè)試。
• 使用 %v 會(huì)混淆你的底層錯(cuò)誤類型，調(diào)用方將無法進(jìn)行匹配，如果有匹配需求，應(yīng)該使用%w動(dòng)詞。

當(dāng)為返回錯(cuò)誤增加上下文信息時(shí)，避免在上下文中增加像 "failed to" 這樣的沒啥用的短語，這樣沒用的短語在錯(cuò)誤 堆棧中堆積起來的話，反而不利于你定位bug。

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

s, err := store.New()
if err != nil {
    return fmt.Errorf(
        "new store: %w", err)
}

failed to x: failed to y: failed to create new store: the error

x: y: new store: the error

然而當(dāng)你的錯(cuò)誤傳給別的系統(tǒng)時(shí)，錯(cuò)誤信息應(yīng)該足夠清晰。(比如, 錯(cuò)誤信息在日志中以 "Failed" 開頭)

其他參考信息：Don't just check errors, handle them gracefully.

錯(cuò)誤命名

對(duì)于全局變量類型，根據(jù)是否導(dǎo)出使用  Err 或 err 前綴。詳情參考：Prefix Unexported Globals with _.

var (
  // 以下兩個(gè)錯(cuò)誤是導(dǎo)出類型，所以他們的命名以 Err 作為開頭，用戶可以使用 errors.Is 來匹配錯(cuò)誤類型
  ErrBrokenLink = errors.New("link is broken")
  ErrCouldNotOpen = errors.New("could not open")

  // 這個(gè)錯(cuò)誤是非導(dǎo)出類型，不會(huì)作為我們公共API的一部分，但是你可以在包內(nèi)使用errors.Is匹配它。
  errNotFound = errors.New("not found")
)

對(duì)于自定義錯(cuò)誤類型，請(qǐng)使用Error后綴。

// 這個(gè)錯(cuò)誤是被導(dǎo)出的，用戶可以使用errors.As去匹配它。
type NotFoundError struct {
  File string
}

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

// 這個(gè)錯(cuò)誤是非導(dǎo)出類型，不會(huì)作為我們公共API的一部分，但是你可以在包內(nèi)使用errors.As匹配它。 

type resolveError struct {
  Path string
}

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

todo：errors.Is和errors.As的區(qū)別

處理斷言失敗

在不正確的類型斷言上 使用單返回值來處理會(huì)導(dǎo)致 panic, 因此請(qǐng)使用 "comma ok" 習(xí)俗.

t := i.(string)

t, ok := i.(string)
if !ok {
  // 在這里優(yōu)雅處理錯(cuò)誤
}

不要使用Panic

在生產(chǎn)環(huán)境的業(yè)務(wù)代碼避免使用panic。Panics 是級(jí)聯(lián)問題cascading failures的主要來源。如果發(fā)生錯(cuò)誤，函數(shù)必須返回錯(cuò)誤，讓調(diào)用方?jīng)Q定如何處理這種情況。

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

func main() {
  run(os.Args[1:])
}

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 不是錯(cuò)誤處理策略。當(dāng)系統(tǒng)發(fā)生像空指針異常這種 不可恢復(fù)的 Fatal 異常時(shí)，才需要使用Panic。唯一的意外情況是項(xiàng)目啟動(dòng)：如果程序啟動(dòng)階段出現(xiàn)問題需要拋出異常。

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

即使在測(cè)試中，優(yōu)先使用t.Fatal 或 t.FailNow 而不是異常，來確保失敗情況被記錄。

// func TestFoo(t *testing.T)

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

// func TestFoo(t *testing.T)

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

使用 go.uber.org/atomic

使用 sync/atomic 包的原子操作對(duì)數(shù)據(jù)類型進(jìn)行操作(int32, int64, 等.) 。因?yàn)樽约翰僮魅菀淄浭褂迷硬僮鲗?duì)變量進(jìn)行讀取和修改。

go.uber.org/atomic 通過隱藏基礎(chǔ)類型為這些操作增加了類型安全性，它還包括一個(gè)很方便的 atomic.Bool 類型.

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

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

避免使用全局可變對(duì)象

Avoid mutating global variables, instead opting for dependency injection. This applies to function pointers as well as other kinds of values.

// sign.go

var _timeNow = time.Now

func sign(msg string) string {
  now := _timeNow()
  return signWithTime(msg, now)
}

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

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

// sign_test.go

func TestSigner(t *testing.T) {
  s := newSigner()
  s.now = func() time.Time {
    return someFixedTime
  }

  assert.Equal(t, want, s.Sign(give))
}

避免在公共結(jié)構(gòu)體中內(nèi)嵌類型

嵌入類型會(huì)暴露實(shí)現(xiàn)細(xì)節(jié)，無法類型演化，讓文檔也變得模糊。

假設(shè)你用AbstractList結(jié)構(gòu)體實(shí)現(xiàn)了公共的 list 方法，避免在其他實(shí)現(xiàn)中內(nèi)嵌AbstractList類型。而是應(yīng)該在其他結(jié)構(gòu)體中顯式聲明list，并在方法實(shí)現(xiàn)中調(diào)用list的方法。

type AbstractList struct {}

// Add adds an entity to the list.
func (l *AbstractList) Add(e Entity) {
  // ...
}

// Remove removes an entity from the list.
func (l *AbstractList) Remove(e Entity) {
  // ...
}

// ConcreteList is a list of entities.
type ConcreteList struct {
  *AbstractList
}

// ConcreteList is a list of entities.
type ConcreteList struct {
  list *AbstractList
}

// Add adds an entity to the list.
func (l *ConcreteList) Add(e Entity) {
  l.list.Add(e)
}

// Remove removes an entity from the list.
func (l *ConcreteList) Remove(e Entity) {
  l.list.Remove(e)
}

Go允許內(nèi)嵌類型type embedding作為組合和繼承的折中方案。外部的結(jié)構(gòu)體會(huì)獲得內(nèi)嵌類型的隱式拷貝。默認(rèn)情況下，內(nèi)嵌類型的方法會(huì)嵌入實(shí)例的同一方法。

外部的結(jié)構(gòu)體會(huì)獲取嵌入類型的同名字段。如果嵌入類型的字段是公開(public)的，那嵌入后也是公開的。為保證向后兼容性，外部結(jié)構(gòu)體未來每個(gè)版本都需要保留嵌入類型。

很少場(chǎng)景需要嵌入類型，雖然嵌入類型很方便，讓你避免編寫冗長的方法。

即使是用interface而不是結(jié)構(gòu)體來嵌入方法，這是給開發(fā)人員帶來了一定的靈活性，但是仍然暴露了具體實(shí)現(xiàn)列表的抽象細(xì)節(jié)。

// AbstractList is a generalized implementation
// for various kinds of lists of entities.
type AbstractList interface {
  Add(Entity)
  Remove(Entity)
}

// ConcreteList is a list of entities.
type ConcreteList struct {
  AbstractList
}

// ConcreteList is a list of entities.
type ConcreteList struct {
  list AbstractList
}

// Add adds an entity to the list.
func (l *ConcreteList) Add(e Entity) {
  l.list.Add(e)
}

// Remove removes an entity from the list.
func (l *ConcreteList) Remove(e Entity) {
  l.list.Remove(e)
}

不管是嵌入結(jié)構(gòu)體還是嵌入接口，都會(huì)限制類型的演化。

• 若嵌入接口，當(dāng)你增加一個(gè)方法是一種破壞性改變
• 若嵌入結(jié)構(gòu)體，當(dāng)你刪除一個(gè)方法是一種破壞性改變
• 刪除嵌入類型是一種破壞性改變
• 即使用滿足接口約束的類型去替換嵌入類型，也是一種破壞性改變

盡管編寫內(nèi)嵌類型已實(shí)現(xiàn)的方法是乏味的。但是這些工作隱藏了實(shí)現(xiàn)細(xì)節(jié)，留下了更多更改的機(jī)會(huì)， 并消除了在文檔中發(fā)現(xiàn)完整List接口的間接方法。

避免使用內(nèi)建命名

Go語言的spec中列舉了一些內(nèi)建命名，在你的Go程序中應(yīng)該避免使用預(yù)聲明的標(biāo)識(shí)符；

根據(jù)上下文的不同，用預(yù)聲明標(biāo)識(shí)符命名變量可能會(huì)在當(dāng)前作用域下覆蓋官方標(biāo)識(shí)符，讓你的代碼變得難以理解。最好的情況下，編譯器會(huì)直接報(bào)錯(cuò)，最糟糕的情況下，這樣的代碼會(huì)引入難以排查的bug。

var error string
// `error` 覆蓋了內(nèi)建的error

// or

func handleErrorMessage(error string) {
    // `error` 覆蓋了內(nèi)建的error
}

var errorMessage string
// `error` 指向內(nèi)置的 error 

// or

func handleErrorMessage(msg string) {
    // `error` 指向內(nèi)置的 error
}

type Foo struct {
    // While these fields technically don't
    // constitute shadowing, grepping for
    // `error` or `string` strings is now
    // ambiguous.
    error  error
    string string
}

func (f Foo) Error() error {
    // `error` and `f.error` are
    // visually similar
    return f.error
}

func (f Foo) String() string {
    // `string` and `f.string` are
    // visually similar
    return f.string
}

type Foo struct {
    // `error` and `string` strings are
    // now unambiguous.
    err error
    str string
}

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

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

注意當(dāng)你使用預(yù)聲明標(biāo)識(shí)符時(shí)編譯器不會(huì)報(bào)錯(cuò)，但是像 go vet 這樣的工具會(huì)告訴你標(biāo)識(shí)符被覆蓋的情況。

避免使用init()

盡可能避免使用init()。如果實(shí)在依賴 init()，可以使用以下方式：

1. 不管程序環(huán)境或調(diào)用方式如何，初始化要完全確定。
2. 避免依賴其他init()函數(shù)的順序或者產(chǎn)生的結(jié)果。雖然init()順序是明確的，但是代碼可以更改。init()函數(shù)之間的關(guān)系會(huì)讓代碼變得易錯(cuò)和脆弱。
3. 避免讀寫全局變量、環(huán)境變量，比如機(jī)器信息、環(huán)境變量、工作目錄，程序的參數(shù)和輸入等等。
4. 避免 I/O 操作，比如文件系統(tǒng)，網(wǎng)絡(luò)和系統(tǒng)調(diào)用。

如果代碼不能滿足這些需求，那可能屬于幫助代碼，需要作為main()函數(shù)的一部分進(jìn)行調(diào)用(或者封裝初始化邏輯，讓main 函數(shù)去調(diào)用)。需要注意的是，被其他模塊依賴的代碼應(yīng)該完全指定初始化順序的確定性，而不是依賴"初始化魔法"。

type Foo struct {
    // ...
}

var _defaultFoo Foo

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

var _defaultFoo = Foo{
    // ...
}

// or, better, for testability:

var _defaultFoo = defaultFoo()

func defaultFoo() Foo {
    return Foo{
        // ...
    }
}

type Config struct {
    // ...
}

var _config Config

func init() {
    // Bad: based on current directory
    cwd, _ := os.Getwd()

    // Bad: I/O
    raw, _ := os.ReadFile(
        path.Join(cwd, "config", "config.yaml"),
    )

    yaml.Unmarshal(raw, &_config)
}

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()函數(shù)可能更具優(yōu)勢(shì)：

• 單個(gè)賦值語句中無法表示的復(fù)雜表達(dá)式
• 插件鉤子，比如 database/sql，編碼信息注冊(cè)表等
• 對(duì) Google Cloud Functions 和其他形式確定性預(yù)計(jì)算的優(yōu)化

優(yōu)雅退出主函數(shù)

Go程序使用os.Exit 或 log.Fatal*來立即退出。(Panic 不是優(yōu)雅的程序退出方式，可以參考 don't panic)

應(yīng)該只在main()函數(shù)里調(diào)用os.Exit 或 log.Fatal*函數(shù)。其他函數(shù)應(yīng)該返回錯(cuò)誤來表示失敗，在main中進(jìn)行退出。

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 := io.ReadAll(f)
  if err != nil {
    log.Fatal(err)
  }

  return string(b)
}

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 := io.ReadAll(f)
  if err != nil {
    return "", err
  }

  return string(b), nil
}

程序中多個(gè)函數(shù)都能退出的話會(huì)有一些問題：

• 不明顯的控制流：多個(gè)函數(shù)都能退出的話，找出程序的控制流會(huì)變得困難。
• 測(cè)試?yán)щy：如果一個(gè)函數(shù)讓程序退出，那它也會(huì)讓測(cè)試退出。這樣會(huì)讓函數(shù)難以測(cè)試。而且可能會(huì)讓go text無法測(cè)試其他函數(shù)。
• 跳過清理：當(dāng)一個(gè)函數(shù)退出程序時(shí)，會(huì)跳過已經(jīng)進(jìn)入defer隊(duì)列的函數(shù)調(diào)用。這樣會(huì)增加跳過清理任務(wù)的風(fēng)險(xiǎn)。

一次性退出

有條件的情況下，main()函數(shù)中最好只調(diào)用os.Exit 或 log.Fatal 一次。如果有多種錯(cuò)誤情況會(huì)停止 程序的執(zhí)行，將這些錯(cuò)誤放在一個(gè)獨(dú)立的函數(shù)中，并返回錯(cuò)誤，main()中處理錯(cuò)誤并退出。

把所有的關(guān)鍵邏輯放在一個(gè)獨(dú)立的可測(cè)試的函數(shù)中，會(huì)讓你的main()函數(shù)變得簡短。

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

  // If we call log.Fatal after this line,
  // f.Close will not be called.

  b, err := io.ReadAll(f)
  if err != nil {
    log.Fatal(err)
  }

  // ...
}

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 := io.ReadAll(f)
  if err != nil {
    return err
  }

  // ...
}

在序列化結(jié)構(gòu)體中使用字段標(biāo)簽。

要編碼成JSON、YAML或其他支持tag格式的結(jié)構(gòu)體字段應(yīng)該用指定對(duì)應(yīng)項(xiàng)tag標(biāo)簽進(jìn)行注釋。

type Stock struct {
  Price int
  Name  string
}

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

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

Rationale: 結(jié)構(gòu)體的序列化方式是不同系統(tǒng)通信的契約。修改結(jié)構(gòu)體的結(jié)構(gòu)和字段會(huì)破壞這個(gè)契約。在結(jié)構(gòu)體中聲明tag 可以防止重構(gòu)結(jié)構(gòu)體中意外違反約定。

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

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

make(map[T1]T2, hint)

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
}

make([]T, length, capacity)

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

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

type Operation int

const (
  Add Operation = iota + 1
  Subtract
  Multiply
)

const EnvVar = "MY_ENV"

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

  // ...
}

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
  )

  // ...
}

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

import (
  "fmt"
  "os"

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

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

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

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

a := 10
if b {
  a = 100
}

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.

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

type Client struct {
  version int
  http.Client
}

type Client struct {
  http.Client

  version int
}

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
}

var s = "foo"

s := "foo"

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

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

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

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

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

printInfo("foo", true, true)

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

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

type Region int

const (
  UnknownRegion Region = iota
  Local
)

type Status int

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

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

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

wantError := `unknown error:"test"`

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

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

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

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

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

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

user := User{}

var user User

sval := T{Name: "foo"}

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

sval := T{Name: "foo"}

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

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

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

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

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

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

$ go vet -printfuncs=wrapf,statusf

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

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

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

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

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

// 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)建一個(gè)連接
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),
)

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)建一個(gè)連接
func Open(
  addr string,
  opts ...Option,
) (*Connection, error) {
  options := options{
    cache:  defaultCache,
    logger: zap.NewNop(),
  }

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

  // ...
}