在前面两个模块，我们回顾了 Go 语言的基础知识，掌握了 Go 项目的开发流程，也完成了爬虫项目的架构设计、功能设计和流程设计。不过，为了写出“好”的代码，我们必须规范代码，这就需要定义好整个团队需要遵守的编程规范了。
我们为什么需要编程规范？
编程规范又叫代码规范，是团队之间在程序开发时需要遵守的约定。俗话说，无规矩不成方圆，一个开发团队应该就一种编程规范达成一致。编程规范有很多好处，我们简单说几个最主要的。
- 促进团队合作
- 规避错误
- 提升性能
- 便于维护 接下来，我们就从这几个维度聊聊制定 Go 编码规范的原则和最佳实践。
整洁、一致
整洁的代码包括对格式化、命名、函数等细节的密切关注，更需要在项目中具体实践。接下来我们就来看看整洁代码关注的这些细节和最佳的实践。
格式化
- 代码长度
代码应该有足够的垂直密度，能够肉眼一次获得到更多的信息。同时，单个函数、单行、单文件也需要限制长度，保证可阅读性和可维护性。
- 一行内不超过 120 个字符，同时应当避免刻意断行。如果你发现某一行太长了，要么改名，要么调整语义，往往就可以解决问题了。
- 单个函数的行数不超过 40 行，过长则表示函数功能不专一、定义不明确、程序结构不合理，不易于理解。当函数过长时，可以提取函数以保持正文小且易读。
- 单个文件不超过 2000 行，过长说明定义不明确，程序结构划分不合理，不利于维护。
- 代码布局
我们先试想一篇写得很好的报纸文章。在顶部，你希望有一个标题，它会告诉你故事的大致内容，并影响你是否要阅读它。文章的第一段会为你提供整个故事的概要、粗略的概念，但是隐藏了所有细节。继续向下阅读，详细信息会逐步增加。
建议Go 文件推荐按以下顺序进行布局。
- 包注释：对整个模块和功能的完整描述，写在文件头部。
- Package：包名称。
- Imports：引入的包。
- Constants：常量定义。
- Typedefs：类型定义。
- Globals：全局变量定义。
- Functions：函数实现。 每个部分之间用一个空行分割。每个部分有多个类型定义或者有多个函数时，也用一个空行分割。示例如下：
/*
注释
*/
package http
import (
"fmt"
"time"
)
const (
VERSION = "1.0.0"
)
type Request struct{
}
var msg = "HTTP success"
func foo() {
//...
}
当 import 多个包时，应该对包进行分组。同一组的包之间不需要有空行，不同组之间的包需要一个空行。标准库的包应该放在第一组。
3.空格与缩进 为了让阅读代码时视线畅通，自上而下思路不被打断，我们需要使用一些空格和缩进。
空格是为了分离关注点，将不同的组件分开。缩进是为了处理错误和边缘情况，与正常的代码分隔开。
较常用的有下面这些规范：
注释和声明应该对齐。示例如下：
type T struct {
name string // name of the object
value int // its value
}
小括号 ()、中括号[]、大括号{} 内侧都不加空格。
逗号、冒号（slice 中冒号除外）前都不加空格，后面加 1 个空格。
所有二元运算符前后各加一个空格，作为函数参数时除外。例如b := 1 + 2。[强制 gofmt] 使用 Tab 而不是空格进行缩进。
return 前方需要加一个空行，让代码逻辑更清晰。
判断语句、for 语句需要缩进 1 个 Tab，并且右大括号}与对应的 if 关键字垂直对齐。例如：
if xxx {
} else {
}
当 import 多个包时，应该对包进行分组。同一组的包之间不需要有空行，不同组之间的包需要一个空行。标准库的包应该放在第一组。这同样适用于常量、变量和类型声明：
import (
"fmt"
"hash/adler32"
"os"
"appengine/foo"
"appengine/user"
"github.com/foo/bar"
"rsc.io/goversion/version"
)
避免 else 语句中处理错误返回，避免正常的逻辑位于缩进中。如下代码实例，else 中进行错误处理，代码逻辑阅读起来比较费劲。
if something.OK() {
something.Lock()
defer something.Unlock()
err := something.Do()
if err == nil {
stop := StartTimer()
defer stop()
log.Println("working...")
doWork(something)
<-something.Done() // wait for it
log.Println("finished")
return nil
} else {
return err
}
} else {
return errors.New("something not ok")
}
如果把上面的代码修改成下面这样会更加清晰：
if !something.OK() {
return errors.New("something not ok")
}
something.Lock()
defer something.Unlock()
err := something.Do()
if err != nil {
return err
}
stop := StartTimer()
defer stop()
log.Println("working...")
doWork(something)
<-something.Done() // wait for it
log.Println("finished")
return nil
函数内不同的业务逻辑处理建议用单个空行加以分割。
注释之前的空行通常有助于提高可读性——新注释的引入表明新思想的开始。
命名
一个好的名字应该满足几个要素：
- 短，容易拼写；
- 保持一致性；
- 意思准确，容易理解，没有虚假和无意义的信息。
例如，像下面这样的命名就是让人迷惑的：
int d; // elapsed time in days
Go 中的命名统一使用驼峰式、不要加下划线。
缩写的专有名词应该大写，例如： ServeHTTP、IDProcessor。
区分变量名应该用有意义的名字，而不是使用阿拉伯数字：a1, a2, … aN。
不要在变量名称中包含你的类型名称。
变量的作用域越大，名字应该越长。
现代 IDE 已经让更改名称变得更容易了，巧妙地使用 IDE 的功能，能够级联地同时修改多处命名。
包名
包名应该简短而清晰。 使用简短的小写字母，不需要下划线或混合大写字母。 合理使用缩写，例如：
strconv（字符串转换）
syscall（系统调用）
fmt（格式化的 I/O）
避免无意义的报名，例如util,common,base等
接口命名
单方法接口由方法名称加上 -er 后缀或类似修饰来命名。例如：Reader, Writer, Formatter, CloseNotifier ，当一个接口包含多个方法时，请选择一个能够准确描述其用途的名称（例如：net.Conn、http.ResponseWriter、io.ReadWriter）。
本地变量命名
尽可能地短。在这里，i 指代 index，r 指代 reader，b 指代 buffer。
例如，下面这段代码就可以做一个简化：
for index := 0; index < len(s); index++ {
//
}
可以替换为:
for i := 0; i < len(s); i++ {
//
}
函数参数命名
如果函数参数的类型已经能够看出参数的含义，那么函数参数的命名应该尽量简短：
func AfterFunc(d Duration, f func()) *Timer
func Escape(w io.Writer, s []byte)
如果函数参数的类型不能表达参数的含义，那么函数参数的命名应该尽量准确：
func Unix(sec, nsec int64) Time
func HasPrefix(s, prefix []byte) bool
函数返回值命名
对于公开的函数，返回值具有文档意义，应该准确表达含义，如下所示：
func Copy(dst Writer, src Reader) (written int64, err error)
func ScanBytes(data []byte, atEOF bool) (advance int, token []byte, err error)
可导出的变量名
由于使用可导出的变量时会带上它所在的包名，因此，不需要对变量重复命名。例如 bytes 包中的 ByteBuffer 替换为 Buffer，这样在使用时就是 bytes.Buffer，显得更简洁。类似的还有把 strings.StringReader 修改为 strings.Reader，把 errors.NewError 修改为 errors.New。
Error 值命名
错误类型应该以 Error 结尾。
Error 变量名应该以 Err 开头。
type ExitError struct {
...
}
var ErrFormat = errors.New("image: unknown format")
函数
圈复杂度（Cyclomatic complexity）<10。 避免使用 init 函数。 Context 应该作为函数的第一个参数。 正常情况下禁用 unsafe。 禁止 return 裸返回，如下例中第一个 return：
func (f *Filter) Open(name string) (file File, err error) {
for _, c := range f.chain {
file, err = c.Open(name)
if err != nil {
return
}
}
return f.source.Open(name)
}
不要在循环里面使用 defer，除非你真的确定 defer 的工作流程。 对于通过:= 进行变量赋值的场景，禁止出现仅部分变量初始化的情况。例如在下面这个例子中，f 函数返回的 res 是初始化的变量，但是函数返回的 err 其实复用了之前的 err：
var err error
res,err := f()
函数返回值大于 3 个时，建议通过 struct 进行包装。
函数参数不建议超过 3 个，大于 3 个时建议通过 struct 进行包装。
控制结构
禁止使用 goto。
当一个表达式为 bool 类型时，应该使用 expr 或 !expr 判断，禁止使用 == 或 != 与 true / false 比较。
if 嵌套深度不大于 5。
方法
receiver 的命名要保持一致，如果你在一个方法中将接收器命名为 “c”，那么在其他方法中不要把它命名为 “cl”。 receiver 的名字要尽量简短并有意义，禁止使用 this、self 等。
func (c Client) done() error {
// ...
}
func (cl Client) call() error {
// ...
}
注释
注释不仅仅可以提供具体的逻辑细节，还可以提供代码背后的意图和决策。
帮助澄清一些晦涩的参数或返回值的含义。一般来说，我们会尽量找到一种方法让参数或返回值的名字本身就是清晰的。但是当它是标准库的一部分时，或者在你无法更改的第三方库中，一个清晰的注释会非常有用。
强调某一个重要的功能。例如，提醒开发者修改了这一处代码必须连带修改另一处代码。
总之，好的注释给我们讲解了 what、how、why，方便后续的代码维护。
无用注释直接删除，无用的代码不应该注释而应该直接删除。即使日后需要，我们也可以通过 Git 快速找到。
紧跟在代码之后的注释，使用 //。
统一使用中文注释，中英文字符之间严格使用空格分隔。
结构体
不要将 Context 成员添加到 Struct 类型中。
高效
Map 在初始化时需要指定长度make(map[T1]T2, hint)。
Slice 在初始化时需要指定长度和容量make([]T, length, capacity)。 我们来看下下面这段程序，它的目的是往切片中循环添加元素。
func createSlice(n int) (slice []string) {
for i := 0; i < n; i++ {
slice = append(slice, "I", "love", "go")
}
return slice
}
从功能上来看，这段代码没有问题。但是，这种写法忽略了一个事实，如下图所示，往切片中添加数据时，切片会自动扩容，Go 运行时会创建新的内存空间并执行拷贝。
自动扩容显然是有成本的。在循环操作中执行这样的代码会放大性能损失，减慢程序的运行速度。。我们可以改写一下上面这段程序，在初始化时指定合适的切片容量：
func createSlice (n int) []string {
slice := make([]string,0,n*3)
for i := 0; i < n; i++ {
slice = append(slice,"I","love","go")
}
return slice
}
这段代码在一开始就指定了需要的容量，最大程度避免了内存的浪费。同时，运行时不需要再执行自动扩容操作，加速了程序的运行。
time.After() 在某些情况下会发生泄露，替换为使用 Timer。
数字与字符串转换时，使用 strconv，而不是 fmt。
读写磁盘时，使用读写 buffer。
谨慎使用 Slice 的截断操作和 append 操作，除非你知道下面的代码输出什么：
x := []int{1, 2, 3, 4}
y := x[:2]
fmt.Println(cap(x), cap(y))
y = append(y, 30)
fmt.Println("x:", x)
fmt.Println("y:", y)
任何书写的协程，都需要明确协程什么时候退出。
热点代码中，内存分配复用内存可以使用 sync.Pool。
将频繁的字符串拼接操作（+=），替换为 StringBuffer 或 StringBuilder。
使用正则表达式重复匹配时，利用 Compile 提前编译。
当程序严重依赖 Map 时，Map 的 Key 使用 int 而不是 string 将。
多读少写的场景，使用读写锁而不是写锁将提速。
健壮性
除非出现不可恢复的程序错误，否则不要使用panic来处理错误，使用error和多返回值。
错误信息不应该首字母大写，也不应该以标点符号结束。因为错误信息通常在其他上下文中被打印。
不要使用 _ 变量来丢弃 error。如果函数返回 error，应该强制检查。
在处理错误时，如果我们逐层返回相同的错误，那么在最后日志打印时，我们并不知道代码中间的执行路径。例如找不到文件时打印的No such file or directory，这会减慢我们排查问题的速度。因此，在中间处理 err 时，需要使用 fmt.Errorf 或第三方包给错误添加额外的上下文信息。像下面这个例子，在 fmt.Errorf 中，除了实际报错的信息，还加上了授权错误信息authenticate failed ：
func AuthenticateRequest(r *Request) error {
err := authenticate(r.User)
if err != nil {
return fmt.Errorf("authenticate failed: %v", err)
}
return nil
}
当有多个错误需要处理时，可以考虑将 fmt.Errorf 放入 defer 中：
func DoSomeThings(val1 int, val2 string) (_ string, err error) {
defer func() {
if err != nil {
err = fmt.Errorf("in DoSomeThings: %w", err)
}
}()
val3, err := doThing1(val1)
if err != nil {
return "", err
}
val4, err := doThing2(val2)
if err != nil {
return "", err
}
return doThing3(val3, val4)
}
利用 recover 捕获 panic 时，需要由 defer 函数直接调用。
例如，下面例子中的 panic 是可以被捕获的：
package main
import "fmt"
func printRecover() {
r := recover()
fmt.Println("Recovered:", r)
}
func main() {
defer printRecover()
panic("OMG!")
}
但是下面这个例子中的 panic 却不能被捕获：
package main
import "fmt"
func printRecover() {
r := recover()
fmt.Println("Recovered:", r)
}
func main() {
defer func() {
printRecover()
}()
panic("OMG!")
}
不用重复使用 recover，只需要在每一个协程的最上层函数拦截即可。recover 只能够捕获当前协程，而不能跨协程捕获 panic，下例中的 panic 就是无法被捕获的。
package main
import "fmt"
func printRecover() {
r := recover()
fmt.Println("Recovered:", r)
}
func main() {
defer printRecover()
go func() {
panic("OMG!")
}()
// ...
}
有些特殊的错误是 recover 不住的，例如 Map 的并发读写冲突。这种错误可以通过 race 工具来检查。
扩展性
利用接口实现扩展性。接口特别适用于访问外部组件的情况，例如访问数据库、访问下游服务。另外，接口可以方便我们进行功能测试。关于接口的最佳实践，需要单独论述。
使用功能选项模式对一些公共 API 的构造函数进行扩展，大量第三方库例如 gomicro、zap 等都使用了这种策略。
db.Open(addr, db.DefaultCache, zap.NewNop())
可以替换为=>
db.Open(
addr,
db.WithCache(false),
db.WithLogger(log),
)
工具
要人工来保证团队成员遵守了上述的编程规范并不是一件容易的事情。因此，我们有许多静态的和动态的代码分析工具帮助团队识别代码规范的错误，甚至可以发现一些代码的 bug。
golangci-lint
而 golangci-lint 是集合多种 Linter 的工具。要查看支持的 Linter 列表以及启用 / 禁用了哪些 Linter，可以使用下面的命令：
golangci-lint help linters
Go 语言定义了实现 Linter 的 API，它还提供了 golint 工具，用于集成了几种常见的 Linter。在源码中，我们可以查看怎么在标准库中实现典型的 Linter。
Linter 的实现原理是静态扫描代码的 AST（抽象语法树），Linter 的标准化意味着我们可以灵活实现自己的 Linters。不过 golangci-lint 里面其实已经集成了包括 golint 在内的总多 Linter，并且有灵活的配置能力。所以在自己写 Linter 之前，建议先了解 golangci-lint 现有的能力。
在大型项目中刚开始使用 golang-lint 会出现大量的错误，这种情况下我们只希望扫描增量的代码。如下所示，可以通过在golangci-lint 配置文件中调整 new-from-rev 参数，配置以当前基准分支为基础实现增量扫描
linters:
enable-all: true
issues:
new-from-rev: master
Pre-Commit
在代码通过 Git Commit 提交到代码仓库之前，git 提供了一种 pre-commit 的 hook 能力，用于执行一些前置脚本。在脚本中加入检查的代码，就可以在本地拦截住一些不符合规范的代码，避免频繁触发 CI 或者浪费时间。pre-commit 的配置和使用方法，可以参考TiDB。
并发检测 race
Go 1.1 提供了强大的检查工具 race 来排查数据争用问题。race 可以用在多个 Go 指令中，一旦检测器在程序中找到数据争用，就会打印报告。这份报告包含发生 race 冲突的协程栈，以及此时正在运行的协程栈。可以在编译时和运行时执行 race，方法如下：
$ go test -race mypkg
$ go run -race mysrc.go
$ go build -race mycmd
$ go install -race mypkg
在下面这个例子中， 运行中加入 race 检查后直接报错。从报错后输出的栈帧信息中，我们能看出具体发生并发冲突的位置。
» go run -race 2_race.go
==================
WARNING: DATA RACE
Read at 0x00000115c1f8 by goroutine 7:
main.add()
bookcode/concurrence_control/2_race.go:5 +0x3a
Previous write at 0x00000115c1f8 by goroutine 6:
main.add()
bookcode/concurrence_control/2_race.go:5 +0x56
第四行 Read at 表明读取发生在 2_race.go 文件的第 5 行，而第七行 Previous write 表明前一个写入也发生在 2_race.go 文件的第 5 行。这样我们就可以非常快速地定位数据争用问题了。
竞争检测的成本因程序而异。对于典型的程序，内存使用量可能增加 5-10 倍，执行时间会增加 2-20 倍。同时，竞争检测器会为当前每个 defer 和 recover 语句额外分配 8 字节。在 Goroutine 退出前，这些额外分配的字节不会被回收。这意味着，如果有一个长期运行的 Goroutine，而且定期有 defer 和 recover 调用，那么程序内存的使用量可能无限增长。（这些内存分配不会显示到 runtime.ReadMemStats 或 runtime / pprof 的输出。）
覆盖率
一般我们会使用代码覆盖率来判断代码书写的质量，识别无效代码。go tool cover 是 go 语言提供的识别代码覆盖率的工具，在后面的课程中还会详细介绍。
总结
代码规范可以助力团队协作、帮助我们写出更加简洁、高效、健壮和可扩展的代码。这节课，我列出了一套 Go 编程规范的最佳实践，并通过 golangci-lint 等工具对不规范甚至是错误的代码进行了强制检查，保证了代码质量。在后面的开发中，我们将严格按照这个规范编写代码。
