Go 编码建议——功能篇

Posted 2022-03-30 恋喵大鲤鱼

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Go 编码建议——功能篇相关的知识，希望对你有一定的参考价值。

文章目录

1.不需要指向 interface 的指针
2.编译期验证 interface 合理性
3.接收器为值和指针实现接口的区别
4.零值 Mutex 是有效的
5.在边界处拷贝 slice 和 map
6.使用 defer 释放资源
7.channel size 要么是 1 或 0
8.枚举从 1 开始
9.使用 time 处理时间
10.关于 error 的处理
13.使用 go.uber.org/atomic 包
14.避免可变全局变量
15.避免在公共结构中嵌入类型
16.避免使用内置标识符
17.主函数退出方式
- 17.1 在 main() 中退出程序
- 17.2 退出一次
18.不要在 for 循环中使用 defer
参考文献

1.不需要指向 interface 的指针

我们几乎不需要使用指向接口的指针，应该将接口直接赋值给接口，这样在传递过程中，实质上传递的底层数据仍然是指针，即不存在值拷贝的情况。

type Foo struct 
	T string


func bar(i interface) 
	...


var foo interface = Foo...

// Bad
bar(&foo)

// Good
bar(foo)

为什么可以这样，因为接口实质上在底层用两个字段表示：
（1）一个指向某些特定类型信息的指针；
（2）一个指向具体数据的指针。如果存储的数据是指针，则直接存储。如果存储的数据是一个值，则存储指向该值的指针。

具体可以看下 Go 源码 runtime 包两种接口类型的定义。

一种是带有一组方法的接口runtime.iface：

type iface struct 
	tab  *itab
	data unsafe.Pointer

一种是不含任何方法的空接口runtime.eface：

type eface struct 
	_type *_type
	data  unsafe.Pointer

我们可以看下接口变量的内存宽度。

var foo interface = Foo...
fmt.Println(unsafe.Sizeof(foo))	// 16

当然，凡事无绝对。如果需要修改接口变量本身，那么应该使用指向接口变量的指针，当然你必须清楚自己在干什么。

类似地，在了解 map、slice、channel 的底层结构后，我们应该知道在传递过程中一般也不需要使用指向它们的指针。

2.编译期验证 interface 合理性

在编译时验证接口的符合性，这包括：
（1）导出类型的部分 API 实现了接口；
（2）导出或非导出类型实现了接口且属于某类型的一部分（匿名嵌套）；
（3）任何其他情况都违反接口合理性检查，终止编译并通知给用户。

上面这 3 条是编译器对接口的检查机制, 错误地使用接口会在编译期报错. 所以可以利用这个机制让部分问题在编译期暴露。

// Bad
type Handler struct 
  // ...


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


// Good
type Handler struct 
  // ...


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

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

如果*Handler与http.Handler的接口不匹配, 那么语句var _ http.Handler = (*Handler)(nil)将无法编译通过。

赋值的右边应该是断言类型的零值。对于指针类型（如 *Handler）、切片和映射是 nil；对于结构类型是空结构。

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


var _ http.Handler = LogHandler

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

3.接收器为值和指针实现接口的区别

接收器为值的方法和接收器为指针的方法在调用方式上是有区别的。

使用值接收器的方法既可以通过值调用，也可以通过指针调用。带指针接收器的方法只能通过指针或 addressable values 调用。

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]S1: "A"

// 你只能通过值调用 Read
sVals[1].Read()

// 编译不通过，因为无法对 sVals[1] 取址
//  sVals[1].Write("test")

sPtrs := map[int]*S1: "A"

// 指针既可以调用 Read，也可以调用 Write
sPtrs[1].Read()
sPtrs[1].Write("test")

类似的，使用值接收器和指针接收器来实现接口，在判断与接口是否匹配时，也存在一定的区别。

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

// 下面代码无法通过编译。因为 s2Val 是一个值，而 S2 的 f 方法中没有使用值接收器
// i = s2Val

为什么可取地址的值可以调用接收器为指针的方法，但是不能将指针接收器方法集和接口匹配的值赋给接口呢？

在 Effective Go 中一节 Pointers vs. Values 做了说明，因为接收器为指针的方法会修改接受器，将一个值赋给接口会产生一个拷贝，将接收器为指针的方法应用到拷贝身上，并不会使修改生效。为了避免产生这种错误的行为，便禁止将值赋给和指针接收器方法集匹配的接口。

4.零值 Mutex 是有效的

零值 sync.Mutex 和 sync.RWMutex 是有效的，所以指向 mutex 的指针基本是不必要的。

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

// Good
var mu sync.Mutex
mu.Lock()

Mutex 作为其他结构体一个字段时，应该使用值而不是指针。即使该结构体不被导出，也不要直接把 Mutex 嵌入到结构体中。

// Bad
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]


// Good
type sMap struct 
  mutex sync.Mutex
  data map[string]string


func NewSMap() *sMap 
  return &sMap
    data: make(map[string]string),
  


func (m *SMap) Get(k string) string 
  m.mutex.Lock()
  defer m.mutex.Unlock()
  return m.data[k]

Bad 部分会导致字段 Mutex、Lock 和 Unlock 方法是 sMap 导出的字段和 API，但又没有明确说明，既导致了模糊的文档，又泄露了 sMap 的实现细节。Good 部分可以做到字段 mutex 及其方法是 sMap 的实现细节，对其调用者不可见。

5.在边界处拷贝 slice 和 map

slice 和 map 包含了指向底层数据的指针，因此在需要复制它们时要特别注意。

在 Go 源码文件 src/runtime/slice.go 我们可以找到切片的底层数据结构 runtime.slice：

type slice struct 
	array unsafe.Pointer
	len   int
	cap   int

在 Go 源码文件 src/runtime/map.go 我们可以找到 map 底层核心数据结构 runtime.hmap：

// A header for a Go map.
type hmap struct 
	// Note: the format of the hmap is also encoded in cmd/compile/internal/reflectdata/reflect.go.
	// Make sure this stays in sync with the compiler's definition.
	count     int // # live cells == size of map.  Must be first (used by len() builtin)
	flags     uint8
	B         uint8  // log_2 of # of buckets (can hold up to loadFactor * 2^B items)
	noverflow uint16 // approximate number of overflow buckets; see incrnoverflow for details
	hash0     uint32 // hash seed

	buckets    unsafe.Pointer // array of 2^B Buckets. may be nil if count==0.
	oldbuckets unsafe.Pointer // previous bucket array of half the size, non-nil only when growing
	nevacuate  uintptr        // progress counter for evacuation (buckets less than this have been evacuated)

	extra *mapextra // optional fields


// mapextra holds fields that are not present on all maps.
type mapextra struct 
	// If both key and elem do not contain pointers and are inline, then we mark bucket
	// type as containing no pointers. This avoids scanning such maps.
	// However, bmap.overflow is a pointer. In order to keep overflow buckets
	// alive, we store pointers to all overflow buckets in hmap.extra.overflow and hmap.extra.oldoverflow.
	// overflow and oldoverflow are only used if key and elem do not contain pointers.
	// overflow contains overflow buckets for hmap.buckets.
	// oldoverflow contains overflow buckets for hmap.oldbuckets.
	// The indirection allows to store a pointer to the slice in hiter.
	overflow    *[]*bmap
	oldoverflow *[]*bmap

	// nextOverflow holds a pointer to a free overflow bucket.
	nextOverflow *bmap

在接收 slice 和 map 时，请记住当 map 或 slice 作为函数参数传入时，如果您存储了对它们的引用，则用户可以对其进行修改。

// Bas
func (d *Driver) SetTrips(trips []Trip) 
	d.trips = trips


trips := ...
d.SetTrips(trips)

// 你是要修改 d.trips 吗？
trips[0] = ...

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


trips := ...
d.SetTrips(trips)

// 这里我们修改 trips[0]，但不会影响 d.trips
trips[0] = ...

在返回 slice 和 map 时，同样的，请注意用户对暴露内部状态的 map 或 slice 的修改。

// Bad
type Stats struct 
  mu sync.Mutex

  counters map[string]int


// Snapshot 返回当前状态。
func (s *Stats) Snapshot() map[string]int 
  s.mu.Lock()
  defer s.mu.Unlock()

  return s.counters


// snapshot 不再受互斥锁保护，可能会引发并发读写的错误
snapshot := stats.Snapshot()

// Good
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 现在是一个拷贝
snapshot := stats.Snapshot()

6.使用 defer 释放资源

使用 defer 释放资源，诸如文件和锁。

// Bad
// 当有多个 return 分支时，很容易遗忘 unlock
p.Lock()
if p.count < 10 
  p.Unlock()
  return p.count


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

return newCount

// Good
// 更可读且安全
p.Lock()
defer p.Unlock()

if p.count < 10 
  return p.count


p.count++
return p.count

defer 的开销非常小，只有在您可以证明函数执行时间处于纳秒级的程度时，才应避免这样做。使用 defer 提升可读性是值得的，因为使用它们的成本微不足道。尤其适用于那些不仅仅是简单内存访问的较大方法，在这些方法中其他计算的资源消耗远超过 defer。

7.channel size 要么是 1 或 0

channel 通常 size 应为 1 或是无缓冲的。默认情况下，channel 是无缓冲的，其 size 为零。任何其他尺寸都必须经过严格的审查，而不是拍脑袋给出一个大致的值。我们需要考虑如何确定大小，什么原因会导致 channel 在高负载下被填满并阻塞写入者，以及当这种情况发生时系统会发生哪些变化。

// Bad
// 应该足以满足任何情况！
c := make(chan int, 64)

// Good
// size 为 1
c := make(chan int, 1) 
// 或无缓冲 size 为 0
c := make(chan int)

8.枚举从 1 开始

Go 并没有关键字 enum 来定义枚举类型，引入枚举的标准方法是声明一个自定义类型和一个使用了自增器 iota 的 const 组来表示枚举值。

预先声明的标识符 iota 表示连续的非类型化整数常量，它的值是对应常量的下标（从零开始），它可用于构造一组相关常数：

type ByteSize float64

const (
    _           = iota // ignore first value by assigning to blank identifier
    KB ByteSize = 1 << (10 * iota)
    MB
    GB
    TB
    PB
    EB
    ZB
    YB
)

由于第一个值从 0 开始，如果需要使第一个值为有意义的值，我们应该从 1 开始。

// Bad
type Operation int

const (
  Add Operation = iota
  Subtract
  Multiply
)
// Add=0, Subtract=1, Multiply=2

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

9.使用 time 处理时间

时间处理很复杂。关于时间的错误假设通常包括以下几点：

（1）一分钟有 60 秒
（2）一小时有 60 分钟
（3）一天有 24 小时
（4）一周有七天
（5）一年 365 天

还有更多，具体可参考 Falsehoods programmers believe about time。

例如，在一个时间点上加上 24 小时并不总是产生一个新的日历日。

为什么常识性的认知是错误的呢？因为地球自转的不均匀性和长期变慢性，会存在时间修正的情况，比如闰秒，闰年等。

因此，在处理时间时始终使用 “time” 包，因为它有助于以更安全、更准确的方式处理这些不正确的假设。

使用 time.Time 表达瞬时时间

在处理时间的瞬间时使用 time.Time，在比较、添加或减去时间时使用 time.Time 中的方法。

// Bad
func isActive(now, start, stop int) bool 
  return start <= now && now < stop


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

使用 time.Duration 表达时间段

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

poll(10) // 是几秒钟还是几毫秒?

// Good
func poll(delay time.Duration) 
  for 
    // ...
    time.Sleep(delay)
  

poll(10*time.Second) // 代码即注释

回到第一个例子，在一个时间时刻加上 24 小时，我们用于添加时间的方法取决于意图。如果我们想要下一个日历日（当前天的下一天）的同一个时间点，我们应该使用 Time.AddDate。但是，如果我们想保证某一时刻比前一时刻晚 24 小时，我们应该使用Time.Add。

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

对外部系统使用 time.Time 和 time.Duration

尽可能在与外部系统交互中使用 time.Time 和 time.Duration 。

（1）Command-line 标志：flag 通过 time.ParseDuration 支持 time.Duration ；

（2）JSON：encoding/json 通过其 Time.UnmarshalJSON 方法支持将 time.Time 编码为 RFC 3339 字符串；

（3）SQL：database/sql 支持将 DATETIME 或 TIMESTAMP 列转换为 time.Time，如果底层驱动程序支持则返回；

（4）YAML：gopkg.in/yaml.v2 支持将 time.Time 作为 RFC 3339 字符串，并通过 time.ParseDuration 支持 time.Duration 。

当不能在这些交互中使用 time.Duration 时，请使用 int 或 float64，并在字段名称中包含单位。

例如，由于 encoding/json 不支持 time.Duration，因此该单位包含在字段的名称中。

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


// Good
// "intervalMillis": 2000
type Config struct 
  IntervalMillis int `json:"intervalMillis"`

当在这些交互中不能使用 time.Time 时，除非达成一致，否则使用 string 和 RFC 3339 中定义的格式时间戳。默认情况下，Time.UnmarshalText 使用此格式，并可通过 time.RFC3339 在 Time.Format 和 time.Parse 中使用。

尽管这在实践中并不成问题，但请记住，time 包不支持解析闰秒时间戳（8728），也不在计算中考虑闰秒（15190）。如果您比较两个时刻，则差异将不包括这两个时刻之间可能发生的闰秒。

10.关于 error 的处理

10.1 错误类型

声明错误可选的方式很少，在选择合适的错误申明方式之前，应考虑以下几点。

（1）调用者是否需要匹配错误以便他们可以处理它？如果是，我们必须通过声明顶级错误变量或自定义类型来支持 errors.Is 或 errors.As 函数。

（2）错误消息是否为静态字符串，还是需要上下文信息的动态字符串？如果是静态字符串，我们可以使用 errors.New，但对于后者，我们必须使用 fmt.Errorf 或自定义错误类型。

（3）我们是否正在传递由下游函数返回的新错误？如果是这样，请参阅错误包装部分。

错误匹配	错误消息	指导
No	static	errors.New
No	dynamic	fmt.Errorf
Yes	static	top-level var with errors.New
Yes	dynamic	custom error type

例如，使用 errors.New 表示带有静态字符串的错误。如果调用者需要匹配并处理此错误，则将此错误导出为变量以支持将其与 errors.Is 匹配。

// Bad

// package foo

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


// package bar

if err := foo.Open(); err != nil 
  // Can't handle the error.
  panic("unknown error")


// Good
// 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 the error
   else 
    panic("unknown error")

对于动态字符串的错误，如果调用者不需要匹配它，则使用 fmt.Errorf，如果调用者确实需要匹配它，则自定义 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 &NotFoundErrorFile: 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")

请注意，如果您从包中导出错误变量或类型，它们将成为包的公共 API 的一部分。

10.2 错误包装

在调用失败时传播错误有三个主要方式：

（1）返回原始错误；
（2）使用 fmt.Errorf 和 %w 添加上下文生成新错误
（3）使用 fmt.Errorf 和 %v 添加上下文生成新错误

如果没有要添加的其他上下文，则按原样返回原始错误。这将保留原始错误类型和消息。这非常适合底层错误消息有足够的信息来追踪它来自哪里的错误。

否则，尽可能在错误消息中添加上下文这样就不会出现诸如“连接被拒绝”之类的模糊错误，您会收到更多有用的错误，例如“呼叫服务 foo：连接被拒绝”。

使用 fmt.Errorf 为你的错误添加上下文，根据调用者是否应该能够匹配和提取根本原因，在 %w 或 %v 格式之间进行选择。

（1）如果调用者应该可以访问底层错误，请使用 %w。对于大多数包装错误，这是一个很好的默认值，但请注意，调用者可能会开始依赖此行为。因此，对于包装错误是已知变量或类型的情况，请将其作为函数契约的一部分进行记录和测试。
（2）使用 %v 来混淆底层错误，调用者将无法匹配它，

以上是关于Go 编码建议——功能篇的主要内容，如果未能解决你的问题，请参考以下文章

Go 编码建议——性能篇

Go 编码规范建议——风格篇

Go语言入门篇-Golang之文本编码处理

Go 编码规范建议