竞态检测器报错但业务没有共享变量的排查路径

我排查过几次 go test -race 报错，最容易误判的地方是：代码里没有一个叫“共享变量”的全局字段，并不代表没有共享内存。闭包可能捕获局部变量，slice 可能复用同一个底层数组，map、指针和测试夹具也可能被多个 goroutine 间接持有。真正有效的入口不是搜索“全局变量”，而是沿报告里的两个访问栈和 goroutine 创建栈，重建它们触碰的同一对象。

官方地址：https://go.dev/doc/articles/race_detector

先看 Read access 与 Previous write 的文件行号，再看它们各自从哪里创建；如果两条栈最终指向同一个可变对象，就按闭包捕获、引用别名、并行测试夹具和组件内部状态四条线排查。修复后必须用同一并发场景再次运行 -race，不能只看普通测试通过。

这次排查的核心：一是确认冲突对象，二是确认对象为什么被两条路径持有，三是把保护边界放在真正共享的位置。

先沿着 race report 重建冲突对象

Go 的竞态报告通常会给出一条读访问、一条此前的写访问，以及相关 goroutine 的创建栈。它描述的是运行时观察到的内存访问，不是“某个函数名字看起来不安全”。我会先把两条访问栈的文件名和行号抄到一张纸上，再向上追到参数、闭包变量或接收者字段，问一句：这两条路径最后拿到的是不是同一个可变对象。

建议先用明确的包和测试范围重跑，减少报告噪声：

# 只跑目标包和目标测试，先固定一条可重复的报告路径
go test -race -run '^TestCacheRead$' ./internal/cache

# 并行测试容易让问题只在部分组合出现，连续跑几次扩大触发机会
go test -race -count=5 ./internal/cache

竞态检测器只能发现实际执行到的冲突。如果报告中某一条栈落在测试辅助函数，不要立即认定辅助函数是根因；继续看它传入的指针、slice 或 map 是否来自同一个 fixture。相反，如果两条栈在不同包里，但共享对象的创建位置相同，应该优先围绕这个对象做最小复现。

没有全局变量也可能共享

我最常见的误判有四种。第一是闭包捕获：循环外声明的 err、计数器或临时指针，被多个 goroutine 的函数体引用。第二是引用类型别名：函数传入的 slice 只复制了描述符，底层数组仍可能相同；map 和指针则更直接。第三是并行测试夹具：t.Parallel() 让多个测试共享包级缓存、环境对象或同一个临时结构。第四是组件内部状态：表面上只调用一个方法，但复用的客户端、缓冲区或回调注册表可能要求串行使用。

func loadBoth(paths []string) []error {
	results := make([]error, len(paths))
	var wg sync.WaitGroup
	wg.Add(len(paths))
	for i, path := range paths {
		go func() {
			defer wg.Done()
			// i 和 path 被闭包共享；并发迭代时应捕获本轮副本。
			results[i] = load(path)
		}()
	}
	wg.Wait()
	return results
}

func loadBothFixed(paths []string) []error {
	results := make([]error, len(paths))
	var wg sync.WaitGroup
	wg.Add(len(paths))
	for i, path := range paths {
		go func(index int, name string) {
			defer wg.Done()
			// 参数是本轮副本；结果槽按 index 独占，避免闭包捕获迭代变量。
			results[index] = load(name)
		}(i, path)
	}
	wg.Wait()
	return results
}

这个例子要同时关注两件事：闭包捕获的变量是否随循环变化，以及 results 的不同下标是否真的由不同 goroutine 独占。即使下标不同，也要确认 load 没有通过共享客户端、全局缓冲区或回调写入同一内部状态。

把测试和依赖内部状态纳入排查边界

如果业务函数本身没有可变全局状态，下一步看测试生命周期。并行子测试可能共同修改环境变量、注册表或包级缓存；测试结束后仍存活的 goroutine 也可能在下一条用例开始后继续写旧对象。可以暂时去掉 t.Parallel() 做对照：如果报告消失，说明问题很可能在夹具隔离或清理时机，而不是“竞态检测器误报”。这只是定位手段，不能作为最终修复。

依赖也要单独确认并发约束。阅读客户端、解码器、缓冲池或回调注册组件的官方文档，确认它是否允许多个 goroutine 同时调用；不要因为外部 API 是只读方法，就假设内部缓存一定是并发安全的。把依赖替换成最小 stub 后再跑一次 -race，若报告消失，就可以把范围收窄到组件使用方式或组件版本。

func TestParallelReads(t *testing.T) {
	fixture := newFixture()
	t.Run("a", func(t *testing.T) {
		// 子测试是否并行，必须与 fixture 的生命周期一起设计。
		t.Parallel()
		_ = fixture.Read("a")
	})
	t.Run("b", func(t *testing.T) {
		// 若 Read 会修改共享缓存，应改为每个子测试独立创建 fixture。
		t.Parallel()
		_ = fixture.Read("b")
	})
}

这里的目标不是把所有并行测试都改成串行，而是先确认共享对象是谁，再决定是每个测试独立实例、给内部状态加锁，还是把调用集中到单一 goroutine。

修复后用同一场景反向验证

修复动作要和冲突对象对应。闭包捕获问题通常传入本轮参数副本；slice 需要确认底层数组是否应深拷贝；map、指针或可变接收者需要互斥锁、所有权转移或串行访问；并行测试则应隔离 fixture 和清理 goroutine。不要只把测试里的 t.Parallel() 删除后就宣布业务代码安全，因为这可能只是绕开触发条件。

我会保留一条回归命令，并记录触发方式、访问栈位置和修复边界：

# 用和修复前相同的测试范围复查，避免只换命令得到假阴性
go test -race -run '^TestCacheRead$' -count=10 ./internal/cache

# 需要扩大覆盖时再跑整个包；报告消失还要结合回归用例判断
go test -race ./internal/cache

最后记住边界：-race 是运行时检测器，不会证明没有执行到的路径绝对安全；启用它还有额外的时间和内存成本。因此结案条件应该是“同一触发场景不再报告、回归测试覆盖共享对象、保护方式与对象生命周期一致”，而不是“普通 go test 通过”。

相关问题

为什么没有全局变量仍会有竞态？局部变量可能被闭包捕获，slice/map/指针可能共享底层对象，测试夹具和依赖内部缓存也可能跨 goroutine 共用。

把 t.Parallel() 删除是不是最终修复？通常不是。它适合做定位对照；如果业务对象本身被并发调用，仍应修复对象的所有权、锁或串行化边界。