Go 竞态检测器

用 -race 在运行时发现未同步的共享内存访问；理解其动态检测本质、开销、与 happens-before/内存模型的关系及局限。

#type / concept #status / growing #tech / dev #resource / go

[!info] 关联笔记

所属 MOC：测试与质量 · 性能与诊断 · 并发

前置概念：Goroutine、Channel、sync 包

语义底座：内存模型、happens-before 与同步

相关：Go 测试、select

Go 竞态检测器

这个概念为什么会出现

数据竞争（data race）是并发里最阴的一类 bug：

同一内存位置
至少一次写
多 goroutine 同时访问
没有 happens-before 关系同步

表现可以是偶发错值、损坏结构、幽灵失败，甚至“只在生产负载出现”。人眼 code review 很难穷尽交错；Go 提供 race detector：在插桩后的运行时跟踪访问与同步事件，发现冲突。

[!abstract] 一句话理解 Race detector 是动态分析工具：在实际执行路径上检测对同一地址的未同步冲突访问；能抓到的取决于测试是否跑到，干净输出也不等于并发设计完美。

最小可运行示例

先把示例放进业务场景，再看代码：

场景：秒杀回写「已售件数」时抓 data race

活动页多个下单成功回调同时执行 sold++。
本地偶发总数不对，CI 想在测试里稳定暴露「未同步写共享计数」。
-race 就是为这类路径准备的：测试里并发调用，让检测器在插桩运行时报警。

// sold.go
package flashsale

// Sold 是进程内已售件数（演示用全局；真实项目应挂在 Service 上并加锁）。
var Sold int

// RecordSale 回写销量：故意无同步，模拟「顺手 ++」的错误实现。
// 业务意图：成功单入账；教学点：多 goroutine 写同一变量即 data race 温床。
func RecordSale() {
	Sold++ // 读改写不是原子的，且无 happens-before
}

// sold_test.go
package flashsale

import "testing"

// TestRecordSaleRace 模拟两个成功单同时回写。
//
// 业务意图：用测试触发并发路径，而不是等生产尖峰。
// 教学点：必须真的并行执行到冲突访问，-race 才会报。
func TestRecordSaleRace(t *testing.T) {
	Sold = 0
	// 带缓冲 done：两个 worker 汇报完成，避免额外同步掩盖问题。
	done := make(chan struct{}, 2)

	go func() {
		RecordSale()
		done <- struct{}{}
	}()
	go func() {
		RecordSale()
		done <- struct{}{}
	}()

	<-done
	<-done
	// 注意：即使数值偶尔是 2，无同步仍是 data race；以 -race 为准。
}

建议运行：

go test -race .

期望：检测器报 WARNING: DATA RACE（读/写栈指向 RecordSale / 测试里的两个 goroutine）。
无 -race 时测试可能默默 PASS——这正是「偶发错数」危险之处。

修复方向：sync.Mutex 保护 Sold、改为 channel 单一 owner 累加、或合适时用 atomic.Int64。

结合场景再看三个关注点

必须跑到竞争路径
只单线程调 RecordSale 不会报警；秒杀测试要真起多个 goroutine。
开销大，用于测与调试
CI 可对关键包 go test -race；默认生产二进制通常不带 -race。
修的是所有权与同步，不是 sleep
time.Sleep 不能建立 happens-before，销量回写仍可能丢更新。

核心概念与准确模型

数据竞争 vs 竞态条件

术语	含义
数据竞争 data race	未同步冲突内存访问；Go 中属严重错误，行为未定义级别的危险
广义 race condition	更广的时序依赖（含逻辑层）；不一定触发 detector

Detector 主攻 data race。逻辑上的“先到先得”错误可能完全不报 race。

工作方式（实现向）

在支持的平台上，-race 构建会：

编译器对内存访问与同步点插桩
运行时维护影子状态（类似 ThreadSanitizer 思路）
对照同步事件（锁、channel、WaitGroup 等）判断是否存在 happens-before

这是 实现工具，不是语言规范的一部分。规范侧定义什么是同步与可见性：见 go-memory-model 与 go-happens-before-and-synchronization。

常用命令

go test -race ./...
go test -race -count=1 ./pkg
go run -race main.go
go build -race -o app.race .

与同步原语的关系

Detector 理解常见同步：

sync.Mutex / RWMutex
channel 发送/接收/关闭
sync.WaitGroup、Once 等
部分 atomic 操作

若你用“自制同步”（仅靠 sleep、无屏障的 flag），detector 会（正确地）报警。

平台与限制

支持平台随 Go 版本变化，需查当前文档
依赖 cgo 工具链在某些平台上的配合
内存占用可数倍增长；大测试可能需调 GORACE 选项

边界情况与反直觉行为

1. 没报 race ≠ 无并发 bug

路径未覆盖、逻辑死锁、取消泄漏、错误的锁粒度都可能静默。

2. 误报极少，漏报看覆盖

通常更该担心没跑到，而不是大量假阳性。

3. 测试里的故意并发要足够交错

只启动一个 goroutine 的“假并发”测不到。使用多个 goroutine、-count、或 t.Parallel 提高触发概率（仍不保证穷尽）。

4. 第三方代码

报告可能指向依赖内部；仍需从你的调用契约理解共享是否越界。

5. 生产开启 -race

极少数诊断场景临时用；默认制品不应带 race，以免性能与资源爆炸。

常见误区

[!warning] 常见误区：用 time.Sleep “修复” race 错误：sleep 让测试变绿。
正确：建立真实 happens-before（锁/channel/atomic 等）。

[!warning] 常见误区：只在本地偶发跑一次错误：从不全量 -race。
正确：CI 对关键包常开；本地改并发必开。

[!warning] 常见误区：把 map 当并发安全错误：多 goroutine 写 map。
正确：sync.Map 或互斥，或分片；并用 -race 验证。

[!warning] 常见误区：认为 atomic 解决所有共享问题错误：对复合不变量只 atomic 单个字段。
正确：不变量需要的同步粒度要覆盖整个临界区。

工程实践

CI：go test -race ./... 至少在主干/夜间；PR 可对变更模块开启。
复现：保留最小测试；报告栈是第一线索。
所有权模型：优先“一个 goroutine 拥有数据”，用 channel 交接。
锁粒度：先正确后细；避免锁顺序死锁（另一类问题）。
与表驱动结合：并发 API 的多场景输入 + race。
文档：包注释写清并发承诺（“Caller must not call X concurrently”）。

type Counter struct {
	mu sync.Mutex
	n  int
}

func (c *Counter) Inc() {
	c.mu.Lock()
	c.n++
	c.mu.Unlock()
}

可验证实验

实验 1：无锁自增

上文 Inc 在 -race 下应报警；加 Mutex 后消失。

实验 2：channel 交接

用 channel 传递唯一所有权的结构体指针，确认无 race。

实验 3：并发 map

两 goroutine 写同一 map，观察报告；再加锁对比。

实验 4：覆盖盲区

写一个“有 race 但测试从不并发调用”的函数，理解为何 CI 绿。

本节总结

本质：动态、执行路径敏感的数据竞争检测。
价值：把偶发内存交错变成可定位栈。
局限：覆盖不到的路径、非 data-race 的并发逻辑错误。
下一步：从工具走向语义——同步保证。

自测题

概念题

构成 data race 的条件是什么？
为什么 -race 干净不能证明并发正确？
sleep 为什么不是同步？

代码推理题

var a, b int
go func() { a = 1; b = 1 }()
for b == 0 {}
fmt.Println(a)

可能出现哪些问题？race detector 可能报什么？

工程思考题

服务在生产每周 panic 一次，本地难复现。如何系统性引入 race 与测试？

参考答案

展开

多 goroutine、同一地址、至少一写、无同步 happens-before。
可能路径未执行；还可能有死锁/逻辑竞态。
不建立内存模型承认的同步事件。
代码题：无同步读 b/a 存在 data race；循环等待属不良同步；a 甚至可能仍见 0（可见性）。
工程题：对并发包补压力测试 + CI -race；用复现日志构造最小并发测试；审查共享状态所有权。

延伸阅读与资料来源

资料	类型	支撑
Data Race Detector	官方文档	用法、选项、开销
Go Memory Model	规范向文档	同步与可见性
Package sync	标准库	互斥与原语
Package atomic	标准库	原子操作
Introducing the Go Race Detector	博客	背景

笔记元信息

建议文件名：go-race-detector.md
所属阶段：阶段五 / 并发质量
学习顺序：会写 goroutine 与测试之后
建议下一篇：happens-before
本篇状态：已深化（书章结构；规范语义 vs 检测工具）