Golang 高质量编程 | 青训营笔记

汪away
113 阅读13分钟

这是我参与「第五营」笔记创作活动的的第4天。

Golang 高质量编程

一、简介

什么是高质量

⭐ 编写的代码能够达到正确可靠、简洁清晰的目标可称之为高质量代码。

  1. 各种边界条件是否考虑完备
  2. 异常情况处理，稳定性保证
  3. 易读易维护

编程原则

⭐ 实际应用场景千变万化，各种语言的特性和语法各不相同，但是高质量编程遵循的原则是相通的。

简单性

  • 消除“多余的复杂性”，以简单清晰的逻辑编写代码
  • 不理解的代码无法修复改进

可读性

  • 代码是写给人看的，而不是机器
  • 编写可维护代码的第一步是确保代码可读

生产力

  • 团队整体工作效率非常重要

二、编码规范

代码格式

⭐ gofmt：Go 语言官方提供的工具，能自动格式化 Go 语言代码为官方统一风格；常见 IDE 都支持方便的配置。

⭐ goimports：也是 Go 语言官方提供的工具，实际等于 gofmt 加上依赖包管理，自动增删依赖的包引用、将依赖包按字母序排序并分类。

注释

Good code has lots of comments, bad code requires lots of comments.

好的代码有很多注释，坏代码需要很多注释。

解释代码作用

⭐ 适合注释公共符号

// Open opens the named file for reading. If successful, methods on
// the returned file can be used for reading; the associated file
// descriptor has mode O_RDONLY.
// If there is an error, it will be of type *PathError.
func Open(name string) (*File, error) {
    return OpenFile(name, O_RDONLY, 0)
}

// Returns true if the table cannot hold any more entries
func IsTableFull() bool

对外提供的函数注释描述它的功能用途，只有在函数的功能简单而明显时才能省略这些注释(例如，简单的取值和设值函数)；另外注释要避色啰嗦，不要对显而易见的内容进行说明，下面的代码中注释就没有必要加上，通过名称可以很容易的知道作用。

解释代码如何做的

⭐ 适合注释实现过程

// Add the Referer header from the most recent
// request URL to the new one, if it's not https->http:
if ref := refererForURL(regs[len(regs)-1].URL, reg.URL); ref != ""{
    reg.Header.Set("Referer", ref)
}

// Process every element in the list
for e:= range elements {
    process(e)
}

对代码中复杂的，并不明显的逻辑进行说明。上面这段代码是给新 url 加上最近的 referer 信息，并不是特别明显，所以注释说明了一下。下面的是一个反例，虽然是对过程注释，但是描述的是显而易见的流程，注意不要用自然语言直接翻译代码作为注释。

解释代码实现的原因

⭐ 适合解释代码的外部因素

⭐ 提供额外上下文

switch resp.StatusCode {
// ...
case 307, 308:
    redirectMethod = regMethod
    shouldRedirect = true
    includeBody = true
    
    if ireq.GetBody == nil && ireq.outgoingLength() != 0 {
        // We had a request body, and 307/308 require
        // re-sending it, but GetBody is not defined. So just
        // return this response to the user instead of an
        // error, like we did in Go 1.7 and earlier.
        shouldRedirect = false
    }
}

注释可以解释代码的外部因素，这些因素脱离上下文后通常很难理解。示例中有一行 shouldRedirect = false 的语句，如果没有注释，无法清楚地明白为什么会设置 false，所以注释里提到了这么做的原因，给出了上下文说明。

解释代码什么情况会出错

⭐ 适合解释代码的限制条件

// parseTimeZone parses a time zone string and returns its length. Time zones
// are human-generated and unpredictable. we can't do precise error checking
// On the other hand, for a correct parse there must be a time zone at the
// beginning of the string, so it's almost always true that there's one
// there. We look at the beginning of the string for a run of upper-case letters.
// If there are more than 5，it's an error.
// If there are 4 or 5 and the last is a T,it's a time zone.
// If there are 3,it's a time zone.
// Otherwise,other than special cases, it's not a time zone.
// GMT is special because it can have an hour offset
func parseTimeZone( value string) (length int, ok bool)

注释应该提醒使用者一些潜在的限制条件或者会无法处理的情况。例如函数的注释中可以说明是否存在性能隐患，输入的限制条件，可能存在哪些错误情况，让使用者无需了解实现细节示例介绍了解析时区字符串的流程，同时对可能遇到的不规范字符串处理进行了说明。

公共符号始终要注释

⭐ 包中声明的每个公共的符号：变量、常量、函数以及结构都需要添加注释

⭐ 任何既不明显也不简短的公共功能必须予以注释

⭐ 无论长度或复杂程度如何，对库中的任何函数都必须进行注释

// ReadAll reads from r until an error or EOF and returns thedata it read.
// A successful call returns err == nil,not err == EOF. BecauseReadAll is
// defined to read from src until EOF， it does not treat an EOFfrom Read
// as an error to be reported.
func ReadAll(r Reader) ([]byte, error)

// Read implements the io.Reader interface.
func (r *FileReader) Read(buf []byte) (int, error)
/*
例外：上述注释没有提供有用的信息。它没有告诉你这个方法做了什么，
更糟糕是它告诉你去看其他地方的文档。
在这种情况下，建议完全删除该注释。
*/

小结

⭐ 代码是最好的注释

⭐ 注释应该提供代码未表达出的上下文信息

命名规范

Good naming is like a good joke. If you have to explain it, it's not funny.

好的命名就像一个好笑话。如果你必须解释它，那就不好笑了。

variable

⭐ 简洁胜于冗长

⭐ 缩略词全大写，但当其位于变量开头且不需要导出时，使用全小写

  • 例如使用 ServeHTTP 而不是 ServeHttp
  • 使用 XMLHTTPRequest 或者 xmIHTTPRequest

⭐ 变量距离其被使用的地方越远，则需要携带越多的上下文信息

  • 全局变量在其名字中需要更多的上下文信息，使得在不同地方可以轻易辨认出其含义
// Bad
for index := 0; index < len(s); index++ {
    // do something
}

// Good
for i := 0; i < len(s); i++ {
    // do something
}

i 和 index 的作用域范围仅限于 for 循环内部时，index 的额外冗长几乎没有增加对于程序的理解。

// Good
func (c *Client) send(req *Request, deadline time.Time)

/ Bad
func (c *Client) send( req *Request, t time.Time )

将 deadline 替换成 t 降低了变量名的信息量，t 常代指任意时间，deadline 指截止时间，有特定的含义。

function

⭐ 函数名不携带包名的上下文信息，因为包名和函数名总是成对出现的

⭐ 函数名尽量简短

⭐ 当名为 foo 的包某个函数返回类型 Foo 时，可以省略类型信息而不导致歧义

⭐ 当名为 foo 的包某个函数返回类型 T 时 (T 并不是 Foo)，可以在函数名中加入类型信息

// Good
func Serve(l net.Listener, handler Handler) error

// Bad
func ServeHTTP(l net.Listener, handler Handler) error

在调用 http 包的 Server 方法时，代码是 http.Server，携带有 http 包名，所以函数名中无需添加包信息。

package

⭐ 只由小写字母组成。不包含大写字母和下划线等字符

⭐ 简短并包含一定的上下文信息。例如 schema、 task 等

⭐ 不要与标准库同名。例如不要使用 sync 或者 strings

⭐ 以下规则尽量满足，以标准库包名为例

  • 不使用常用变量名作为包名。例如使用 bufio 而不是 buf
  • 使用单数而不是复数。例如使用 encoding 而不是 encodings
  • 谨慎地使用缩写。例如使用 fmt 在不破坏上下文的情况下比 format 更加简短

小结

⭐ 核心目标是降低阅读理解代码的成本

⭐ 重点考虑上下文信息，设计简洁清晰的名称

控制流程

避免嵌套，保持正常流程清晰

// Bad
if foo {
    return x
} else {
    return nil
}

// Good
if foo {
    return x
}
return nil

如果两个分支中都包含 return 语句，则可以去除冗余的 else

尽量保持正常代码路径为最小缩进

// Bad
func OneFunc() error {
    err := doSomething()
    if err == nil {
        err := doAnotherThing()
        if err == nil {
            return nil // normal case
         }
        return err
    }
    return err
}

// Good
func OneFunc() error {
    if err := doSomething(); err != nil {
        return err
    }
    if err := doAnotherThing(); err != nil {
        return err
    }
    return nil // normal case
}

调整后的代码从上到下就是正常流程的执行过程

优先处理错误情况/特殊情况

func (b *Reader) UnreadByte() error {
    if b.lastByte < 0 || b.r == 0 && b.w > 0 {
        return ErrInvalidUnreadByte
    }
    //b.r > 0 || b.w == 0
    if b.r > 0 {
        b.r--
    } else {
        // b.r == 0 && b.w == 0
        b.w = 1
    }
    b.buf[b.r] = byte(b.lastByte)
    b.lastByte = -1
    b.lastRuneSize = -1
    return nil
}

优先处理 err 情况，尽早返回或继续循环来减少嵌套，保持正常流程的统一

小结

⭐ 线性原理，处理逻辑尽量走直线，避免复杂的嵌套分支

⭐ 正常流程代码沿着屏幕向下移动

⭐ 提升代码可维护性和可读性

⭐ 故障问题大多出现在复杂的条件语句和循环语句中

错误和异常处理

简单错误

⭐ 简单的错误指的是仅出现一次的错误，且在其他地方不需要捕获该错误

⭐ 优先使用 errors.New 来创建匿名变量来直接表示简单错误

⭐ 如果有格式化的需求，使用 fmt.Errorf

func defaultCheckRedirect(req *Request， via []*Request) error {
    if len(via) >= 10 {
        return errors.New("stopped after 10 redirects")
    }
    return nil
}

错误的 Wrap 和 Unwrap

⭐ 错误的 Wrap 实际上是提供了一个 error 嵌套另一个 error 的能力，从而生成一个 error 的跟踪链

⭐ 在 fmt.Errorf 中使用 :%w 关键字来将一个错误关联至错误链中

list, -, err := c.GetBytes(cache.Subkey(a.actionID,"srcfiles"))
if err != nil {
    return fmt.Errorf("reading srcfiles list: %w", err)
}

错误判定

⭐ 判定一个错误是否为特定错误，使用 errors.Is

  • 不同于使用 == 该方法可以判定错误链上的所有错误是否含有特定的错误
data, err = lockedfile.Read(targ)
if errors.Is(err, fs.ErrNotExist) {
    // Treat non-existent as empty, to bootstrap the "latest" file
    // the first time we connect to a given database.
    return []bytef}, nil
}
return date, err

⭐ 在错误链上获取特定种类的错误，使用 errors.As

if _, err := os.Open("non-existing"); err != nil {
    var pathError *fs.PathError
    if errors.As(err, &pathError) {
        fmt.Println("Failed at path:", pathError.Path)
    } else {
        fmt.Println(err)
    }
}

panic

⭐ 不建议在业务代码中使用 panic

⭐ 调用函数不包含 recover 会造成程序崩溃

⭐ 若问题可以被屏蔽或解决，建议使用 error 代替 panic

⭐ 当程序启动阶段发生不可逆转的错误时可以在 init 或 main 函数中使用 panic

func main() {
    //...
    ctx, cancel := context.WithCancel(context.Background())
    client, err := sarama.NewConsumerGroup(strings.Split(brokers, ","), group, config)
    if err != nil {
        log.Panicf("Error creating consumer group client: %v"， err)
    }
}

// Panicf is equivalent to Printf() followed by a call to panic().
func Panicf(format string, v ...interface[}) {
    s := fmt.Sprintf(format, v...)
    std.Output(2, s)
    panic(s)
}

recover

⭐ recover 只能在被 defer 的函数中使用

⭐ 嵌套无法生效

⭐ 只在当前 goroutine 生效

⭐ defer 的语句是后进先出

func (s *ss) Token(skipSpace bool， f func(rune) bool)(tok []byte, err error) {
    defer func() {
        if e := recover(); e != nil {
            if se, ok := e.(scanError); ok {
                err = se.err
            } else {
                panic(e)
            }
        }
    }()
    // ...
}

⭐ 如果需要更多的上下文信息，可以 recover 后在 log 中记录当前的调用栈

func (t *treeFS) Open(name string) (f fs.File, err error) {
    defer func() {
        if e := recover(); e != nil {
            f = nil
            err = fmt.Errorf("gitfs panic: %v\n%s", e, debug.Stack())
        }
    }()
    // ...
}

小结

⭐ error 尽可能提供简明的上下文信息链，方便定位问题

⭐ panic 用于真正异常的情况

⭐ recover 生效范围，在当前 goroutine 的被 defer 的函数中生效

三、性能优化建议

⭐ 性能优化的前提是满足正确可靠、简洁清晰等质量因素

⭐ 性能优化是综合评估，有时候时间效率和空间效率可能对立

⭐ 针对 Go 语言特性，介绍 Go 相关的性能优化建议

Benchmark

⭐ 性能表现需要实际数据衡量，Go 语言提供了支持基准性能测试的 benchmark 工具：go test -bench=. -benchmen

// from fib.go
func Fib(n int) int {
    if n < 2 {
            return n
    }
    return Fib(n-1) + Fib(n-2)
}

// from fib_test.go
func BenchmarkFib10(b *testing.B) {
    // run the Fib function b.N times
    for n := 0; n < b.N; n++ {
            Fib(10)
    }
}
image.png

BenchmarkFib10 是测试函数名，-16 表示 GOMAXPROCS 的值为16

4202122 表示一共执行了 4202122 次，即 b.N 的值

284.3 ns/op 表示每次执行花费 284.3 ns 0 B/op 表示每次执行申请多大的内存 0 allocs/op 表示每次执行申请几次内存

Slice

预分配内存

⭐ 尽可能在使用 make() 初始化切片时提供容量信息

func NoPreAlloc(size int) {
    data := make([]int, 0)
    for k := 0; k < size; k++ {
        data = append(data, k)
    }
}

func PreAlloc(size int) {
    data := make([]int, 0, size)
    for k := 0; k < size; k++ {
        data = append(data, k)
    }
}
image.png

⭐ 切片本质是一个数组片段的描述

type slic struct {
    array unsafe.Pointer
    len int
    cap int
}

⭐ 切片操作并不复制切片指向的元素

⭐ 创建一个新的切片会复用原来切片的底层数组

陷阱：大内存未释放

⭐ 在已有切片基础上创建切片，不会创建新的底层数组

⭐ 原切片较大，代码在原切片基础上新建小切片，原底层数组在内存中有引用，得不到释放

⭐ 可使用 copy 替代 re-slice

func GetLastBySlice(origin []int) []int {
    return origin[len(origin)-2:]
}

func GetLastByCopy(origin []int) []int {
    result := make([]int, 2)
    copy(result, origin[len(origin)-2:])
    return result
}

func testGetLast(t *testing.T, f func([]int) []int) {
    result := make([][]int, 0)
    for k := 0; k < 100; k++ {
        origin := generateWithCap(128 * 1024) // 1M
        result = append(result, f(origin))
    }
    printMem(t)
    _ = result
}
image.png

Map

⭐ map 预分配内存

func NoPreAlloc(size int) {
    data := make(map[int]int)
    for i := 0; i < size; i++ {
        data[i] = 1
    }
}

func PreAlloc(size int) {
    data := make(map[int]int, size)
    for i := 0; i < size; i++ {
        data[i] = 1
    }
}
image.png

不断向 map 中添加元素的操作会触发 map 的扩容

提前分配好空间可以减少内存拷贝和 Rehash 的消耗

建议根据实际需求提前预估好需要的空间

字符串处理

func Plus(n int, str string) string {
    s := ""
    for i := 0; i < n; i++ {
            s += str
    }
    return s
}

func StrBuilder(n int, str string) string {
    var builder strings.Builder
    for i := 0; i < n; i++ {
            builder.WriteString(str)
    }
    return builder.String()
}

func ByteBuffer(n int, str string) string {
    buf := new(bytes.Buffer)
    for i := 0; i < n; i++ {
            buf.WriteString(str)
    }
    return buf.String()
}
image.png

使用 + 拼接性能最差，strings.Builder，bytes.Buffer 相近，strings.Buffer 更快

分析

  • 字符串在 Go 语言中是不可变类型，占用内存大小是固定的
  • 使用 + 每次都会重新分配内存
  • strings.Builder，bytes.Buffer 底层都是 []byte 数组
  • 内存扩容策略不需要每次拼接重新分配内存
// bytes.Buffer
// To build strings more efficiently, see the strings.Builder type.
func (b *Buffer) String() string {
    if b == nil {
        // Special case, useful in debugging.
        return "<nil>"
    }
    return string(b.buf[b.off:])
} 

// strings.Buffer
// String returns the accumulated string.
func (b *Builder) String() string {
    return *(*string)(unsafe.Pointer(&b.buf))
}

bytes.Buffer 转化为字符串时重新申请了一块空间

strings.Builder 直接将底层的 []byte 转换成了字符串类型返回

func PreStrBuilder(n int, str string) string {
    var builder strings.Builder
    builder.Grow(n * len(str))
    for i := 0; i < n; i++ {
            builder.WriteString(str)
    }
    return builder.String()
}

func PreByteBuffer(n int, str string) string {
    buf := new(bytes.Buffer)
    buf.Grow(n * len(str))
    for i := 0; i < n; i++ {
            buf.WriteString(str)
    }
    return buf.String()
}
image.png

字符串拼接和 slice 一样，同样支持预分配，在预知字符串长度的情况下，我们可以进一步提升拼接性能。注意这里能确认 string.builer 只有一次内存分配，byte.buffer 有两次

空结构体

⭐ 空结构体 struct{} 实例不占据任何的内存空间

⭐ 可作为各种场景下的占位符使用

  • 节省资源
  • 空结构体本身具备很强的语义，即这里不需要任何值，仅作为占位符
func EmptyStructMap(n int) {
    m := make(map[int]struct{})

    for i := 0; i < n; i++ {
        m[i] = struct{}{}
    }
}

func BoolMap(n int) {
    m := make(map[int]bool)

    for i := 0; i < n; i++ {
        m[i] = false
    }
}
image.png

⭐ 实现 Set，可以考虑用 map set 开源实现

  • 对于这个场景，只需要用到 map 的键，而不需要值
  • 即使是将 map 的值设置为 bool 类型，也会多占据 1 个字节空间

atomic 包

⭐ 多线程场景

type atomicCounter struct {
    i int32
}

func AtomicAddOne(c *atomicCounter) {
    atomic.AddInt32(&c.i, 1)
}

type mutexCounter struct {
    i int32
    m sync.Mutex
}

func MutexAddOne(c *mutexCounter) {
    c.m.Lock()
    c.i++
    c.m.Unlock()
}
image.png

锁的实现是通过操作系统来实现，属于系统调用

atomic 操作是通过硬件实现，效率比锁高

sync.Mutex 应该用来保护一段逻辑，不仅仅用于保护一个变量

一个对于非数值操作，可以使用 atomic.Value，能承载一个 interface{}

小结

⭐ 避免常见的性能陷阱可以保证大部分程序的性能

⭐ 普通应用代码，不要一味地追求程序的性能

⭐ 越高级的性能优化手段越容易出现问题

⭐ 在满足正确可靠、简洁清晰的质量要求的前提下提高程序性能

四、源代码

⭐ 性能对比测试代码：GitHub - RaymondCode/go-practice

avatar
文章
阅读
粉丝