这是我参与「第三届青训营 -后端场」笔记创作活动的的第 1 篇笔记

高质量编程

什么是高质量

各种边界条件考虑完备
异常情况处理, 稳定性保证
易读易维护

编程原则

简单性

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

可读性

确保代码可读, 降低维护难度
代码是写给人看的, 而不是机器

生产力

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

编码规范

编写高质量的代码需注意:

代码格式
注释
命名规范
控制流程
错误和异常处理

工具

gofmt: Go 语言官方提供的工具, 能自动格式化 Go 语言代码为官方统一风格
goimports: 也是 GO 语言官方提供的工具, 实际等于 gofmt 加上依赖包管理, 可以自动增删依赖的包引用、将依赖包按字母排序并分类

注释

注释应该做到
- 解释代码的作用
- 解释代码如何做的。适合注释实现过程。
- 解释代码实现的原因。适合解释代码的外部因素或者提供额外的上下文，以便维护人员评估改动的影响。
- 解释代码什么情况下会出错。适合解释代码的限制条件，便于他人理解代码。
公共符号 始终要注释
- 包中声明的每个公共的符号：**变量、常量、函数、以及结构 **都需要添加注释。
- 任何既 不明显 也 不简短 的 公共功能 必须予以注释。
- 无论长度或复杂程度如何，对库中的任何函数都必须进行注释。
- 实现接口的方法不需要注释。

命名规范

variable（变量）

简洁胜于冗长
缩略词全大写，但当其位于变量开头且不需要导出（暴露给外部使用）时，使用全小写。
- 例如，使用 ServeHTTP 而不是 ServerHttp
- 使用 XMLHTTPRequest 或者 xmlHTTPRequest
变量距离其被使用的地方越远，则需要携带越多的 上下文信息
- 全局变量 在其名字中需要更多的 上下文信息，使得在不同地方可以轻易辨认出其含义

// Bad
for index := 0; index < len(s); index++{
	// do something
}
// Good
// i 和 index 的作用域仅限于 for 循环内部时, index 的额外冗长可以省略, 因其并没有增加对于程序的理解
for i := 0; i < len(s); i{
	// do something
}

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

// Bad
func (c *Client) send (req *Request, t time.Time)
// 将 deadline 替换成 t 降低了变量名的信息量

function(函数/方法名)

函数名不携带包名的上下文信息，因为它们总是成对出现的。如，http 包下的 Server 函数，调用时使用 http.Server ，那么我们在定义函数时，就不需要定义成 ServerHTTP。
函数名尽量简短。
当名为 foo 的包某个函数返回类型 Foo 时，可以省略类型信息而不导致歧义。
当名为 foo 的包某个函数返回类型 T 时，可以在函数名中加入类型信息。

package（包名）

只由小写字母组成。不包含大写字母和下划线等字符。
简短并包含一定的上下文信息。例如，schema、task 等。
不要与标准库同名。

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

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

小结

命名规范的出发点以及核心是降低他人（自己）阅读理解代码的成本。
重点考虑上下文信息，设计简洁清晰的名称。

控制流程

避免嵌套，保持正常流程清晰
尽量保持正常代码路径为最小缩进
- 优先处理错误情况、特殊情况。尽早返回或继续循环来减少嵌套
小结
- 线性原理，逻辑尽量走直线，避免复杂的嵌套分支
- 正常流程代码沿着屏幕向下移动
- 提升代码可维护性和可读性
- 故障问题大多出现在复杂的条件语句和循环语句中

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

错误和异常处理

简单错误

简单的错误指仅出现一次的错误，且在其他地方不需要捕获该错误
优先使用 errors.New 来创建匿名变量，以直接表达简单错误
如果有格式化的需求，使用 fmt.Errorf

func defaultCheckRedirect(req *Request, via []*Request) error{
    if len(via) >= 10{
        return error.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{
    // Treat non-existent as empty, to bootstrap the "lastest" file 
    // the first time we connect to a given database
    return fmt.Errorf("reading srcfiles list: %W", err)
}

错误判定

使用 errors.Is 判定一个错误是否为特定错误
不同于 ==，使用该方法可以判定错误链上的所有错误是否含有特定的错误
在错误链上获取特定种类的错误，使用 errors.As

data, err = lockedfile.Read(targ)
if errors.Is(err, fs.ErrNotExist){
    return []byte{}, nil
}
return data, err

panic(宕机/程序崩溃)

不建议在业务代码中使用 panic
调用函数不包含 recover 会造成程序崩溃
若问题可以被屏蔽或解决，建议使用 error 代替 panic
当程序启动阶段发生不可逆转的错误时，可以在 init 或 main 函数中使用 panic

recover（恢复）

recover 只能在被 defer 的函数中使用
嵌套无法生效
只能在当前 goroutine 生效
defer 的语句是后进先出
如果需要更多的上下文信息，可以在 recover 后再 log 中记录当前的调用栈

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

小结

error 尽可能提供简明的上下文信息链，方便定位问题
panic 用于真正异常的情况
recover 生效范围，在当前 goroutine 的被 defer 的函数中生效

性能优化

简介

性能优化的前提是满足正确可靠、简洁清晰等质量因素
性能优化是综合评估，有时 时间效率 和 空间效率 可能对立（需要空间换时间，或者反过来）

Benchmark

性能表现需要实际数据衡量
Go 语言提供了支持 基准性能测试 的 benchmark 工具

// 终端中使用 go test -bench=. -benchmem 运行 (windows 下需要改成-bench='.')
// from fib_test.go
fuc Fib（n int) int{
    if n<2 {
        return n
    }
}
// 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)
    }
}
/*
输出
goos: windows				//运行环境
goarch: amd64				//CPU架构
pkg: GoStudy/Benchmark		//包名
cpu: Intel(R) Core(TM) i5-9300H CPU @ 2.40GHz	
//函数名				执行次数,即 b.N 的值	 每次执行花费的毫秒数	  执行申请多大的内存  申请几次内存
BenchmarkFib10-8         4886326               243.1 ns/op             0 B/op         0 allocs/op
PASS					//执行通过
ok      GoStudy/Benchmark       1.711s

*/

slice 预分配内存

尽可能在使用 make() 初始化切片时提供容量信息
切片的本质是一个数组片段的描述
- 包括数组指针
- 片段的长度、容量（不改变内存分配情况下的最大长度）
切片操作并不复制切片指向的元素
创建一个新的切片会复用原来切片的底层数组

进行 append 操作时，当切片的容量不足以容纳新元素时，会申请一块更大的内存，然后拷贝原来的元素，追加新元素到新内存，同时，数组指针也会指向新内存空间，长度也随之改变

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)
	}
}
// 测试
func BenchmarkPreAlloc(b *testing.B) {
	// run the Fib function b.N times
	for n := 0; n < b.N; n++ {
		NoPreAlloc(100)
	}
}
func BenchmarkNoPreAlloc(b *testing.B) {
	// run the Fib function b.N times
	for n := 0; n < b.N; n++ {
		NoPreAlloc(100)
	}
}
// BenchmarkNoPreAlloc-8       1977146               571.6 ns/op          2040 B/op          8 allocs/op
// BenchmarkPreAlloc-8         5280114               221.1 ns/op          896 B/op          1 allocs/op
// 可以看到预分配后, 申请内存只有 1 次, 并且申请的内存更少, 执行时间低了几乎 3 倍

另一个陷阱：大内存未释放

在已有切片基础上创建新切片，不会创建新的底层数组
场景
- 原切片较大，代码在原切片基础上新建小切片
- 原底层数组因在内存中有引用，不会进行垃圾回收，得不到释放
可使用 copy 替代 re-slice

map 预分配内存

map 也是常用的结构，也可以预分配内存优化性能。

不断向 map 中添加元素的操作会触发 map 的扩容
提前分配好空间可以减少内存拷贝和 Rehash 的消耗
建议根据实际需求提前预估好需要的空间

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

// BenchmarkNoPreAlloc-8      17061             70702 ns/op           86554 B/op         64 allocs/op
// BenchmarkPreAlloc-8        40993             29070 ns/op           41097 B/op          6 allocs/op

字符串处理 - 使用 strings.Builder

常用的字符串拼接方式有 "+" 、strings.Builder 以及 bytes.Buffer
- 分析
  - 字符串在 Go 语言中是不可变类型，占用内存大小是固定的。
  - 每次使用 “+” 都会重新分配内存。
  - strings.Builder，bytes.Buffer 底层都是 []byte 数组。
  - 内存扩容策略，不需要每次拼接重新分配内存。
实际测试 最慢的 是 "+"操作，它的申请内存次数也是最多的，strings.Builder 的性能比 bytes.Buffer 稍快, 但是申请内存比 bytes.Buffer 更多
- bytes.Buffer 转化为字符串时重新申请了一块空间。
- strings.Builder 直接将底层的 []byte转换成了字符串类型返回。
同样的，进行内存预分配可以减少 Builder 和 Buffer 申请内存的次数和每次申请内存的大小。预分配使用 Builder.Grow()，Buffer.Grow()。

使用空结构体节省内存

空结构体 struct{} 实例不占据任何内存空间
可作为各种场景下的占位符使用。有以下优点:
- 节省资源
- 空结构体本身具备很强的语义，即这里不需要任何值，仅作为占位符

atomic（原子操作）包

锁的实现是通过操作系统来实现的，属于系统调用
atomic 操作是通过硬件实现，效率比锁更高
sync.Mutex 应该用来保护一段逻辑，不仅仅用于保护一个变量
对于非数值操作，可以使用 atomic.Value，能承载一个 interface{}

type atomicCounter struct{
    i int32
}
func AtomicAddOne(c *atomicCounter){
    atomic.AddInt32(&c.i,1)
}
// BenchmarkAtomicAddOne-8     75244544               13.74 ns/op            4 B/op          1 allocs/op

type mutexCounter struct{
    i int32
    m sync.Mutex
}
func MutexAddOne(c *mutexCounter){
    c.m.Lock()
    c.i++
    c.m.Unlock()    
}
//BenchmarkMutexAddone-8     38081697                28.33 ns/op           16 B/op          1 allocs/op
// 用 Atomic 可以显著提高性能

小结

避免常见的性能陷阱可以保证大部分程序的性能
对于普通应用代码，不要一味地追求程序的性能
越高级的性能优化手段越容易出现问题
在满足正确可靠、简洁清晰的质量要求的前提下提高程序性能

性能调优实战

性能调优原则

依靠数据而不是猜测
要定位最大瓶颈而不是细枝末节
不要 过早优化
不要 过度优化

性能分析工具 pprof

pprof 是用于 可视化 和 分析性能，分析数据 的工具
通过 pprof 可以知道什么地方耗费了多少 CPU、Memory
- 支持分析 - Profile。可分析网页、可视化终端
- 支持采样 - Sample 不同类型的数据，如 CPU、堆内存-Heap、协程-Goroutine、锁-Mutex、阻塞-Block、线程创建-ThreadCreate。

高质量编程和性能优化 | 青训营笔记

高质量编程

什么是高质量

编程原则

简单性

可读性

生产力

编码规范

工具

注释

命名规范

variable（变量）

function(函数/方法名)

package（包名）

小结

控制流程

错误和异常处理

简单错误

错误的 Wrap 和 Unwrap

错误判定

panic(宕机/程序崩溃)

recover（恢复）

小结

性能优化

简介

Benchmark

slice 预分配内存

另一个陷阱：大内存未释放

map 预分配内存

字符串处理 - 使用 strings.Builder

使用空结构体节省内存

atomic（原子操作） 包

小结

性能调优实战

性能调优原则

性能分析工具 pprof

atomic（原子操作）包