11 常见陷阱与工程惯例

一句话：Go 的坑大多来自「值语义、nil、共享底层数据」三件事；每个坑都能用「现象 → 原因 → 正确写法」拆开，记住原因比记住补丁有用。

适用 Go 1.22+。部分行为随版本变化，篇内已标注；不确定时以官方文档为准。

为什么需要

Go 的语法简单，但简单不等于没有边界。切片和 map 的共享语义、nil 的多种形态、循环变量和 defer 的执行时机，都会在代码看起来「没问题」时埋下故障。把这些模式固化成工程惯例，比出事后逐个排查便宜。

核心机制

下面每条都按「现象 → 原因 → 正确写法」组织。

1. nil map 写入 现象：panic: assignment to entry in nil map。原因：map 零值是 nil，读、len、delete 安全，但没有底层哈希表可写。正确：m := map[K]V{} 或 make(map[K]V)，需要容量时用 make(map[K]V, n)。

2. 切片别名 现象：改 b 影响了 a，或 append 后原切片尾部被覆盖。原因：切片 header 复制，底层数组共享；cap 够时 append 原地写。正确：需要独立副本用 slices.Clone 或 copy；只读视图用三索引 s[i:j:k] 限制 cap；不要长期持有大数组的小切片。

3. 循环变量 现象：闭包或 goroutine 全部拿到最后一个值。原因：Go 1.21 及更早整个循环共用一个变量；1.22 起每次迭代一份。正确：基线 1.22+ 可直接捕获；要兼容旧版本或表达更清楚，用 v := v 或把值作为参数传入。

4. 循环里的 defer 现象：文件、连接直到函数返回才关闭，循环大时句柄耗尽。原因：defer 注册在当前函数，返回时才执行。正确：把循环体包进匿名函数，或显式 Close；错误用 errors.Join 汇总。

5. goroutine 闭包捕获 现象：所有 goroutine 打印同一个值，或捕获了大对象导致内存不降。原因：闭包捕获变量本身，启动时机不确定。正确：把循环变量作为参数传入 go func(v int) { ... }(v)；只捕获必要字段。

6. time.After 泄漏 现象：循环或长连接里定时器越积越多，内存上涨。原因：每次 time.After 都创建 Timer；Go 1.23 起不可达的 Timer 可被回收，但分配仍在。正确：循环里用 time.NewTimer 加 Stop/Reset，或复用 context.WithTimeout。

7. string 与 []byte 转换 现象：热路径分配高，GC 压力大。原因：[]byte(s) 和 string(b) 默认复制。正确：转换一次后复用；拼接用 strings.Builder，字节处理用 bytes.Buffer；不要为了省复制滥用 unsafe。

8. 浮点比较 现象：0.1+0.2 == 0.3 为 false，排序或去重结果不稳定。原因：二进制浮点不能精确表示多数十进制小数，NaN 连自己都不等于。正确：用 math.Abs(a-b) < eps 做容差比较；判 NaN 用 math.IsNaN；金额用整数最小单位或 decimal。

9. WaitGroup 复用 现象：panic: sync: WaitGroup is reused before previous Wait has returned，或计数错乱。原因：Add 在 Wait 之后、或计数为 0 时与 Wait 并发。正确：启动 goroutine 前 Add，Done 配对；上一轮 Wait 返回后再复用；不要复制 WaitGroup。

10. 错误被忽略 现象：失败被当成成功，或资源没释放。原因：_ = f()、没检查 Close、defer 里的错误被丢掉。正确：处理或显式注释为什么忽略；写文件时把 Close 错误 join 进返回值；用 errcheck 或 staticcheck 兜底。

11. 包命名与布局 现象：util、common、models 越来越多，导入循环，包名和目录名不一致导致阅读困难。原因：按技术分层而不是按业务边界组织。正确：包名短、小写、能说明职责；按领域拆包；对外入口放 cmd/，内部实现放 internal/；不要建万能工具包。

最小上手

package main

import (
	"fmt"
	"math"
	"slices"
	"sync"
)

func main() {
	m := map[string]int{} // 不是 var m map[string]int
	m["x"]++

	a := []int{1, 2, 3}
	b := slices.Clone(a) // 新底层数组，不共享
	b[0] = 9
	fmt.Println(a, b) // [1 2 3] [9 2 3]

	var wg sync.WaitGroup
	for _, v := range []int{1, 2, 3} {
		wg.Add(1)
		go func(v int) { // 显式传参，不依赖循环变量语义
			defer wg.Done()
			fmt.Print(v, " ")
		}(v)
	}
	wg.Wait()
	fmt.Println()

	fmt.Println(math.Abs(0.1+0.2-0.3) < 1e-9) // true
}

完整版本见 examples/11_pitfalls/main.go。运行：go run examples/11_pitfalls/main.go。

生产动作

• 代码检查：go vet ./...、staticcheck ./...、errcheck ./... 进 CI；锁复制、printf 参数、结构体 tag 由 vet 先兜住。
• 并发检查：go test -race ./...；长跑服务用 goleak 在测试退出时抓泄漏。
• 评审清单：看到 append、go func、defer 在循环里、map 写入、time.After、浮点相等，就停下来确认所有权和生命周期。
• 约定写进文档：包命名、错误包装、日志边界、context 传递，团队统一，减少「每个人一套」。
• 基准验证：性能相关改动用 -benchmem 和 benchstat，不要凭感觉判断分配。

边界

• 这些是高频模式，不是完整缺陷列表；并发和内存问题仍要靠 profile 和 race。
• Go 1.22 的循环变量语义只影响新编译的代码，依赖旧行为的代码升级后可能改变输出。
• slices.Clone 是浅拷贝，元素含指针时内部仍共享。
• 容差比较的 eps 要按业务量级选，没有通用值。
• sync.Map、unsafe、cgo 有各自边界，不能套用上面的简单规则。
• 工具能发现的问题有限，设计层面的所有权和关闭纪律仍要人保证。

讲清楚

Go 的常见坑集中在三件事：值语义、nil 和共享底层数据。数组和 struct 赋值复制，切片和 map 复制的是描述符或指针，所以 append 在 cap 内会改到原数组；nil map 可读不可写，typed nil 放进接口又不等于 nil。循环变量在 1.22 前共用、之后每次一份；defer 在循环里会累积；goroutine 闭包捕获变量而不是值。工程上把这些固化成检查：go vet、staticcheck、-race，评审时看到 append、go func、defer 循环、map 写入就确认所有权和生命周期。记住原因，别只记补丁，换一种写法时先问数据归谁，才知道边界在哪。

适用 Go 1.22+ | 初稿 2026-10