Go 测试怎样为 t.Parallel 隔离可变状态

表驱动测试加上 t.Parallel() 后，最容易出现的不是“并行没有生效”，而是每个子测试读到的值和你以为的不一样：闭包还没有真正执行，父测试已经继续修改循环变量；或者多个子测试拿着同一个切片、map，一边断言一边改数据。结果就是测试偶尔通过、偶尔失败，甚至只在 -race 下暴露问题。

官方文档：https://pkg.go.dev/testing

要让并行子测试稳定，先把当前用例值固定在子测试自己的作用域，再把会被修改的切片、map 或对象复制成私有副本。只读夹具可以共享，但可变状态不能因为“只是测试”就共用。

t.Parallel 什么时候真正执行

t.Run 会启动子测试函数。子测试如果直接返回，就按普通方式完成；如果调用 t.Parallel()，它会先暂停，让父测试继续推进。父测试函数返回后，这些已经声明并行的子测试才会彼此并行执行。testing 包的这个语义允许父测试把一组子测试组织起来，但也意味着闭包捕获的变量不一定在调用 t.Parallel 后马上被读取。

下面的写法把 tc 直接交给闭包。问题不在 t.Run 本身，而在闭包读取的是外层变量；当子测试暂停时，外层循环可能已经进入下一轮。

func TestParseUnsafe(t *testing.T) {
	tests := []struct {
		name string
		input string
		want  int
	}{
		{name: "one", input: "one", want: 1},
		{name: "two", input: "two", want: 2},
	}

	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			t.Parallel() // 子测试可能先暂停，闭包主体稍后才继续。
			if got := parseCount(tc.input); got != tc.want {
				t.Fatalf("got %d, want %d", got, tc.want)
			}
		})
	}
}

对于使用 go 1.21 或更早语言语义的模块，这类代码可能让多个闭包看到最后一轮的循环变量。Go 1.22 起，模块语言版本为 go1.22 或更高时，循环变量会按每次迭代创建新的绑定；但明确复制仍然能表达“这个子测试拥有自己的用例值”，也能让代码兼容旧模块和不同构建设置。不要只凭本机 Go 版本判断项目行为，还要看 go.mod 中的语言版本。

为每个子测试固定当前用例

最直接的修复是在进入 t.Run 前复制当前用例。复制可以是结构体值复制，也可以只复制闭包真正使用的字段。这样子测试闭包捕获的是当前迭代的局部变量，而不是继续变化的循环变量。

func TestParseSafe(t *testing.T) {
	tests := []struct {
		name string
		input string
		want  int
	}{
		{name: "one", input: "one", want: 1},
		{name: "two", input: "two", want: 2},
	}

	for _, tc := range tests {
		tc := tc // 为当前迭代创建副本，闭包只捕获这个副本。
		t.Run(tc.name, func(t *testing.T) {
			t.Parallel() // 副本已固定，暂停后仍对应当前用例。
			if got := parseCount(tc.input); got != tc.want {
				t.Fatalf("got %d, want %d", got, tc.want)
			}
		})
	}
}

如果结构体里含有指针、切片或 map，外层结构体复制只会复制这些字段的引用。此时“固定用例值”和“隔离可变数据”是两件事：tc := tc 解决循环变量的绑定问题，不能自动复制 tc.payload 指向的底层数组，也不能复制 tc.options 指向的 map。

隔离会被修改的切片和 map

并行测试可以共享只读数据。例如一份不会被修改的常量表、解析规则或测试字典，只要其内部对象确实没有写操作，就可以由多个子测试读取。真正需要警惕的是测试过程中会被追加、删除、排序或写入的切片和 map。

遇到可变夹具时，优先在每个子测试内部创建副本。浅复制适合元素本身不可变的场景；如果切片元素或 map value 仍然指向可变对象，还要按对象层级继续复制，直到子测试之间不再共享写入路径。

func cloneStrings(src []string) []string {
	// 新建底层数组，避免子测试的排序或追加改到原始用例。
	dst := make([]string, len(src))
	copy(dst, src)
	return dst
}

func cloneCounts(src map[string]int) map[string]int {
	// map 不能用 copy 复制，逐项写入新的 map 才能隔离后续修改。
	dst := make(map[string]int, len(src))
	for key, value := range src {
		dst[key] = value
	}
	return dst
}

func TestNormalizeParallel(t *testing.T) {
	baseTags := []string{"go", "test"}
	baseCounts := map[string]int{"go": 1}

	for _, name := range []string{"trim", "sort"} {
		name := name // 固定子测试名称对应的闭包变量。
		t.Run(name, func(t *testing.T) {
			t.Parallel()
			tags := cloneStrings(baseTags)       // 每个子测试独占可变切片。
			counts := cloneCounts(baseCounts)    // 每个子测试独占可变 map。
			_ = normalize(name, tags, counts)    // 被测函数可以安全修改副本。
		})
	}
}

这里的副本不是为了让测试“看起来并行”，而是为了让测试数据的所有权清晰：父测试保留基线，子测试拥有自己的工作数据。若被测函数本身会保存传入切片或 map 的引用，还要在测试设计中明确它的生命周期，不能仅靠测试调用方的复制掩盖生产代码的共享状态。

初始化和清理应该放在哪一层

父测试适合准备所有子测试都只读的公共夹具，例如一份固定配置或不可变输入。子测试自己的临时目录、可写缓冲区和会变化的服务客户端，应在子测试内部创建。这样每个子测试可以独立清理，失败时也不会把另一个子测试的状态带进来。

func TestFilesParallel(t *testing.T) {
	fixture := []byte("read-only fixture") // 父测试创建后不再修改。

	for _, name := range []string{"first", "second"} {
		name := name
		t.Run(name, func(t *testing.T) {
			t.Parallel()
			dir := t.TempDir() // 每个子测试拥有独立目录，测试结束后自动清理。
			buf := append([]byte(nil), fixture...) // 可写缓冲区使用独立底层数组。
			t.Cleanup(func() {
				_ = removeTestFiles(dir) // 清理本子测试创建的额外资源。
			})
			if err := writeFixture(dir, buf); err != nil {
				t.Fatalf("write fixture: %v", err)
			}
		})
	}
}

调用 t.Parallel 前的代码与父测试继续循环之间存在时序关系，初始化如果依赖并行执行，应放在调用之后；不过初始化若必须串行完成，也可以明确放在调用之前。关键是不要把一个会被子测试修改的对象留在父测试作用域，然后期待 t.Parallel 自动替你复制它。

t.Cleanup 会在当前测试及其子测试完成后执行，适合登记关闭连接、删除临时资源等动作。清理函数同样不要写入其他并行子测试正在使用的共享对象；否则资源生命周期隔离仍然没有完成。

什么时候可以共享，什么时候必须加锁

共享不一定错误，关键在于共享对象是否只读，以及访问它的代码是否允许并发。只读配置、不可变字节序列和不会延迟修改的查找表通常可以共享；缓存、统计计数器、复用的缓冲区、临时文件名生成器和会改变顺序的切片则要格外谨慎。

如果业务逻辑本来就需要共享状态，可以使用互斥锁、原子操作或并发安全容器。但这会把测试从“彼此独立的并行用例”变成“围绕同一个临界区排队的用例”。锁只能保护同步访问，不能修复错误的断言、错误的对象生命周期，也不能让一个不安全的外部依赖突然变成并发安全。

type counter struct {
	mu sync.Mutex
	n  int
}

func (c *counter) Add(delta int) {
	c.mu.Lock()
	defer c.mu.Unlock() // 无论后续逻辑如何返回，都释放互斥锁。
	c.n += delta
}

func (c *counter) Value() int {
	c.mu.Lock()
	defer c.mu.Unlock() // 读取也必须遵守同一把锁的保护范围。
	return c.n
}

上面的类型本身可以并发访问，但在单元测试里，若每个子测试只需要一个计数器，通常直接为每个子测试创建一个更简单。只有当测试目标就是验证共享计数器的并发语义时，才值得把共享对象和锁保留下来。

用 go vet 和 -race 找到剩余风险

完成复制后，仍要检查被测函数内部是否保存了外部引用。go vet 能帮助发现一部分循环闭包问题；官方 loopvar 说明也特别提到，Go 1.21 改进了 loopclosure 分析器。它不是完整的并发证明，但适合作为提交前的静态提醒。

# 先检查当前包及其依赖中的常见静态问题。
go vet ./...

# 用竞态检测器运行测试，观察共享写入和不安全读取。
go test -race ./...

# 重复执行同一组测试，放大依赖执行顺序的偶发问题。
go test -count=50 -run 'TestParse|TestNormalize' ./...

-race 只能发现实际运行路径上的数据竞争；没有被覆盖到的分支仍然可能存在共享状态问题。反过来，测试偶发失败也不必直接归因于数据竞争，闭包捕获错误、随机输入、时间依赖和资源清理顺序都需要分别判断。可先看失败用例是否固定、再看是否存在对同一地址的并发读写，最后缩小到单个子测试。

一套可以直接套用的表驱动模板

把几个边界合起来，模板应包含四个动作：复制当前用例、调用 t.Parallel、为可变字段建副本、在子测试内完成资源清理。用例结构尽量保存输入和期望值，不要把共享服务状态藏在全局变量里。

func TestFeatureParallel(t *testing.T) {
	tests := []struct {
		name  string
		input []string
		want  string
	}{
		{name: "empty", input: nil, want: ""},
		{name: "items", input: []string{"b", "a"}, want: "a,b"},
	}

	for _, tc := range tests {
		tc := tc // 固定本轮结构体值，避免旧语言语义下的闭包复用。
		t.Run(tc.name, func(t *testing.T) {
			t.Parallel()
			input := append([]string(nil), tc.input...) // 隔离被测函数可能修改的切片。
			got, err := feature(input)
			if err != nil {
				t.Fatalf("feature: %v", err)
			}
			if got != tc.want {
				t.Fatalf("got %q, want %q", got, tc.want)
			}
		})
	}
}

如果 feature 会异步保存 input 的引用，测试还需要根据这个函数的契约决定是否在调用前后都复制；如果它要求调用方不得再修改输入，就可以把切片视为只读。测试代码要和被测 API 的所有权约定一致，而不是机械地给每个值都加一层复制。

常见问题

Go 1.22 之后还需要写 tc := tc 吗？

如果模块使用 go 1.22 或更高语言版本，循环变量按每次迭代绑定，旧问题通常不会再以同样方式出现。保留显式副本仍然可以突出每个子测试的所有权，也便于代码在旧模块、不同工具链或混合仓库中保持一致。

所有并行子测试都必须复制测试数据吗？

不必。只读数据可以共享；只有会被修改、会被延迟使用，或内部包含可变引用的数据才需要按层级复制。复制的目标是隔离写入路径，不是把整个输入对象无条件深拷贝。

给共享 map 加锁是不是最稳妥？

加锁可以保护并发访问，但它会改变测试目标和执行特征。如果每个子测试本来就应该互不影响，创建私有 map 更清楚；只有测试确实要验证共享状态的并发行为时才使用锁。

为什么本地单独运行通过，批量运行才失败？

单独运行可能没有触发并行交错或闭包延迟读取。批量运行、提高重复次数和 -race 会改变调度机会，但它们不是修复手段。回到子测试的变量绑定、可变数据所有权和清理时机，通常能找到根因。

最终可以记住一个顺序：先固定闭包看到的当前用例，再判断字段是否可变；可变字段在子测试内复制，只读夹具才共享；需要验证共享并发时才加锁，并用 go vet、-race 和重复运行检查遗漏。这样 t.Parallel 带来的速度提升，才不会换成难以复现的测试污染。