并行子测试捕获循环变量的结果异常原因

你在Go中写带`t.Parallel()`的并行子测试时，经常会遇到所有子测试拿到的循环变量值全是迭代的最后一项，和你预期的每个子测试对应不同循环项完全不符，这个问题不是测试框架的bug，是循环变量地址复用加上并行goroutine的调度时序错位共同导致的。

Go的for循环会复用同一个迭代变量的栈内存地址，并行子测试启动后会等父测试阻塞的过程中，外层循环已经把迭代变量跑完赋值成最后一个值，所有闭包捕获的是同一个变量的引用，最后读取到的自然都是最后一次循环写入的值。

先说结论：并行子测试出现“所有用例都拿到了最后一条数据”，通常不是 JSON 解码随机出错，而是 t.Parallel() 把真正的测试执行推迟到了外层循环结束之后。在 Go 1.21 及更早的模块语义中，循环变量可能被多个闭包共同捕获；在 Go 1.22 及以后，模块声明为 go 1.22 或更高版本时，循环变量改为每轮独立。

如果需要兼容旧模块，最稳妥的修复仍然是在进入 t.Run 前显式复制当前用例。本文只围绕 table-driven JSON 解码测试说明这个现象、定位方法和最小修复。

官方资料：https://go.dev/doc/

问题为什么只在并行子测试里暴露

下面的测试写法看起来很自然：先遍历 JSON 测试用例，再为每个用例创建子测试。真正的危险点在于，t.Parallel() 不会让当前函数立刻并发执行；它会标记子测试为并行，并让父测试继续向下运行。

func TestDecode(t *testing.T) {
	tests := []decodeCase{
		{name: "number", input: "{\"id\":1}", want: 1},
		{name: "string", input: "{\"id\":2}", want: 2},
		{name: "empty", input: "{}", want: 0},
	}

	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			// 并行子测试先登记，父循环结束后才真正继续执行。
			t.Parallel()
			got := decodeID(tc.input)
			if got != tc.want {
				t.Fatalf("got %d, want %d", got, tc.want)
			}
		})
	}
}

在旧的循环变量语义下，三个闭包捕获的是同一个 tc。当父函数走完循环时，tc 已经指向最后一条记录；等并行子测试被释放，多个测试就可能同时读取最后一条记录，于是错误表现为“结果全一样”或“只有最后一个用例真正生效”。

先确认是捕获问题，而不是解码问题

排查时不要一上来修改 JSON 解析器。先做两个对照：暂时去掉 t.Parallel()，再查看模块的语言版本。如果去掉并行后结果恢复，说明“子测试执行时机”很可能参与了问题；如果仍然错误，再回头检查解码字段、零值和断言。

# 先确认当前测试属于哪个模块，避免只看机器上的 Go 工具链版本。
go env GOMOD

# 只运行这个测试并关闭测试缓存，观察每条用例的实际名称和失败位置。
go test -run '^TestDecode$' -count=1 -v

# 查看模块声明的语言版本；它决定循环变量语义是否切换。
sed -n '1,8p' go.mod

这里有一个容易混淆的边界：使用较新的 Go 工具链，并不等于所有模块自动获得 Go 1.22 的循环变量语义。模块的 go 行仍然是重要线索。Go 1.22 及以后，只有声明为 go 1.22 或更高版本的模块才使用新的每轮变量语义；旧模块仍可能保留旧行为。

兼容旧模块的最小修复

如果项目还不能立即把 go.mod 升到 1.22，直接在循环体内复制一次变量即可。复制发生在当前迭代中，闭包捕获到的是本轮独立的 tc，不会再依赖父循环结束时的最终值。

func TestDecode(t *testing.T) {
	tests := loadDecodeCases()
	for _, tc := range tests {
		tc := tc // 为旧模块创建本轮副本，兼容 t.Parallel 的延迟执行。
		t.Run(tc.name, func(t *testing.T) {
			t.Parallel() // 只并行执行互不修改共享状态的测试。
			got := decodeID(tc.input)
			if got != tc.want {
				t.Fatalf("got %d, want %d", got, tc.want)
			}
		})
	}
}

也可以把当前用例作为参数传给一个辅助函数，但核心原则没有变化：让闭包绑定本轮数据，而不是绑定会在下一轮继续变化的变量。这个写法对 Go 1.21 及更早模块最有价值；迁移到 Go 1.22 后保留它也不会降低可读性。

JSON 解码数据怎样安全地交给并行测试

如果测试表来自 JSON，通常可以先一次性解码，再在每个子测试中只读自己的副本。json.RawMessage 底层是字节切片：只读没有问题，但不要在并行子测试中修改同一片底层数组，也不要让测试之间共享会被写入的 map、slice 或指针字段。

type decodeCase struct {
	Name  string          `json:"name"`
	Input json.RawMessage `json:"input"`
	Want  int             `json:"want"`
}

func TestJSONCases(t *testing.T) {
	cases := loadFromJSON()
	for _, tc := range cases {
		tc := tc // 固定当前结构体；Input 在本例中只读。
		t.Run(tc.Name, func(t *testing.T) {
			t.Parallel() // 子测试不能写回 cases 或共享的嵌套可变对象。
			got, err := decodeID(tc.Input)
			if err != nil {
				t.Fatalf("decode input: %v", err)
			}
			if got != tc.Want {
				t.Fatalf("got %d, want %d", got, tc.Want)
			}
		})
	}
}

注意，复制结构体只是复制字段值。如果结构体内还有 map、slice 或指针，并且测试会修改它们，就需要为每个用例做深复制，或者改成每个子测试独立创建输入。否则即使循环变量捕获已经修好，也可能因为共享可变数据产生真正的数据竞争。

Go 1.22 之后还要不要写 tc := tc

如果模块的 go.mod 已经声明 go 1.22 或更高版本，循环变量按每次迭代创建，原先的闭包捕获问题会被语言语义修复。可以理解为下面两条路线：

不要把“升级工具链”和“升级模块语言版本”混为一谈。团队如果维护多个模块，应该以每个模块自己的 go.mod 为判断依据。

一份可以复用的排查清单

1. 确认异常是否只出现在调用 t.Parallel() 的子测试中。
2. 检查循环体是否把 tc、i 或指针字段交给了闭包。
3. 读取当前模块的 go.mod，不要只看 go version。
4. 旧模块先加 tc := tc，再判断是否还有共享可变状态。
5. JSON 测试表只读共享；会被修改的 map、slice、指针对象要为每个子测试独立创建。
6. 最后恢复并行执行，使用 go test -run ... -count=1 -v 做定向回归。

这类问题的关键不是把并行测试全部关掉，而是分清“子测试什么时候执行”和“闭包捕获了哪个变量”。先固定循环变量，再处理共享数据，通常能用很小的改动恢复稳定结果。

相关问题

为什么去掉 t.Parallel 后测试就通过了？

去掉后子测试会在父循环推进到下一轮前执行，旧循环变量还没有被改成最后一条数据，所以问题被暂时遮住了。它不能证明闭包写法本身安全。

升级到 Go 1.22 后还需要修改旧测试吗？

对于声明为 go 1.22 或更高版本的模块，循环变量捕获通常不再需要额外复制；但共享 map、slice 和指针对象的并发写入仍然需要单独处理。

JSON 解码失败和循环变量捕获怎么区分？

先把 t.Parallel() 临时移除并打印每条用例的名称，再检查输入字段和错误返回。如果输入本身正确、只有并行时多条用例变成同一个结果，优先检查循环变量捕获。