让并发 Bug 无处藏身：-race、阻塞剖析与 Goroutine 泄漏定位
“并发测试跑了很多次都没问题”不能证明没有并发 Bug。数据竞争、死锁和 goroutine 泄漏是三类不同故障，需要不同证据和工具。
先做故障分类
flowchart TD
S["并发症状"] --> R{"共享内存无同步？"}
R -->|是| RD["Race Detector"]
R -->|否| B{"程序卡住或延迟高？"}
B -->|是| BP["阻塞 / Mutex Profile + Trace"]
B -->|goroutine 数持续增长| GP["Goroutine Profile + 生命周期审计"]
RD --> F["修复所有权或同步关系"]
BP --> F
GP --> F
- 数据竞争：至少两个 goroutine 并发访问同一内存，至少一个是写，且缺少同步。
- 死锁/活锁/竞争严重：可能没有数据竞争，但程序无法推进或锁等待过长。
- 泄漏：goroutine 永久等待，任务已经失去业务价值却仍占着栈、定时器、连接或引用对象。
Race Detector 只检查第一类，不是并发正确性的总证明。
用 -race 跑真实路径
go test -race ./...
go test -race -run TestCache -count=20 ./internal/cache
go build -race -o app-race ./cmd/app它只能发现运行期间实际发生的竞争。因此除了单元测试，还应让带 race 的二进制经过集成测试或预发布流量。官方文档给出的典型开销约为 2–20 倍运行时间、5–10 倍内存，不适合不评估就全量上线。
报告通常给出两个冲突访问的栈，以及创建相关 goroutine 的栈：
WARNING: DATA RACE
Write at ...
cache.(*Cache).Put()
Previous read at ...
cache.(*Cache).Get()
Goroutine ... created at ...从“同一个地址被谁读写”出发，而不是只在报告行附近加锁。真正的修复可能是：把状态限制在单 goroutine、通过 channel 转移所有权、用 mutex 保护完整不变量，或发布不可变快照。
不要用 //go:build !race 排除失败测试来“修复”报告；该标签只适合确实无法在检测器约束下运行的少数场景。GORACE="halt_on_error=1 strip_path_prefix=/workspace/" 可用于 CI 快速失败和缩短路径。
阻塞剖析：程序在等什么
阻塞 profile 统计 goroutine 在 channel、mutex 等同步点被阻塞的时间；mutex profile 关注锁竞争。它们默认不开或采样，应在可控范围内启用：
runtime.SetBlockProfileRate(1) // 每次阻塞都采样，开销高
runtime.SetMutexProfileFraction(10) // 约每 10 次竞争采样一次然后通过 runtime/pprof 写文件，或在受保护的管理端口暴露 net/http/pprof：
go tool pprof http://127.0.0.1:6060/debug/pprof/block
go tool pprof http://127.0.0.1:6060/debug/pprof/mutexflat 高表示时间直接归属该函数，cum 高表示它调用的路径累计等待多。采样率会影响数值，不要把不同配置下的绝对值直接比较。
泄漏定位：先看趋势，再看栈聚类
sequenceDiagram
participant M as 指标
participant P as pprof
participant C as 代码审计
M->>M: goroutine 数随请求持续增长
M->>P: 低负载时抓基线
M->>P: 故障后再抓一次
P->>P: 按相同等待栈聚类
P->>C: 定位创建点和退出条件
C->>C: 补取消、关闭或结果消费
curl -s 'http://127.0.0.1:6060/debug/pprof/goroutine?debug=2' > goroutines.txt
go tool pprof http://127.0.0.1:6060/debug/pprof/goroutine重点不是某一刻“有 500 个 goroutine”，而是在相似负载下是否持续增长，以及增长部分是否聚集在同一等待栈。常见栈包括：
- 无接收者的 channel send；
- 没有截止时间的网络读取；
Ticker创建后无人停止；- 启动后台任务后既不取消也不等待；
- 下游提前返回，流水线上游仍尝试发送。
测试可以在操作前后比较 goroutine profile 或数量，但运行时自身也有后台波动，不能只用 runtime.NumGoroutine() 的严格相等作为证据。更可靠的是让组件暴露 Close/Wait，用超时断言所有工作协程收敛，并检查目标栈不再存在。
Go 1.26 还提供实验性的 goroutine leak profile，可辅助识别已无法影响程序结果的 goroutine；它需要实验开关，不能替代清晰的生命周期设计，详见本系列的 Go 1.26 特别篇。
一套日常策略
- CI 对单元和集成测试运行
-race，并让并发路径有足够覆盖。 - 服务记录 goroutine 数、线程数、连接池等待和队列深度趋势。
- 受保护地保留 pprof 入口，故障时抓 goroutine、block、mutex 和 trace。
- 每个
go语句在评审中回答：谁取消、谁等待、它最迟何时退出？
进一步阅读：Data Race Detector、Go Diagnostics。