Go WaitGroup Add 放在 Wait 后面为什么不可靠

我在整理一段并发任务代码时，最容易被忽略的不是 Done 少写了一次，而是把 Add 放进了新 goroutine，随后马上调用 Wait。这段代码看起来像“先启动任务，再等待任务”，但 WaitGroup 并不会等待未来才发生的 Add：当计数器仍是零时，Wait 可能直接返回。

可靠的规则很简单：如果正向 Add 发生时计数器为零，它必须先于 Wait；实际编码中通常就是先 Add，再创建 goroutine。把这条规则当成任务创建的安全边界，能避免主流程提前结束、结果没收集完，甚至触发 WaitGroup 的并发误用。

官方文档入口：https://pkg.go.dev/sync#WaitGroup.Add。本文只讨论 Add 的时机与并发启动顺序，不延伸到 channel 关闭或更复杂的任务调度。

我先保护什么：等待的是已经登记的任务

WaitGroup 的核心资产不是 goroutine 本身，而是一个任务计数器。每次 Add(1) 把计数器加一，每次 Done() 把它减一；Wait() 只负责等计数器归零。它没有“看到未来 goroutine 后自动补登记”的能力。

var wg sync.WaitGroup

// 先登记任务数量，再把任务交给新的 goroutine。
wg.Add(1)
go func() {
	defer wg.Done() // 无论任务正常返回还是中途 return，都配对减一。
	doWork()
}()

wg.Wait() // 等已经登记的任务完成，而不是等待未来的 Add。

这里的顺序表达了一个清晰契约：主流程创建任务之前，计数器已经从零变成一；任务完成后，Done 让计数器回到零，Wait 才能返回。代码阅读者不需要猜测任务是否已经被登记。

风险路径：为什么 Add 放进 goroutine 后会失去可靠性

下面这种写法的问题在于，Add(1) 和 Wait() 属于不同的并发上下文。调度器可以先运行主 goroutine，让它在计数器仍为零时调用 Wait；此时等待条件已经满足，Wait 会返回，之后新 goroutine 才有机会执行 Add。

var wg sync.WaitGroup

go func() {
	// 错误边界：Add 与 Wait 竞争，任务可能尚未登记。
	wg.Add(1)
	defer wg.Done()
	doWork()
}()

wg.Wait() // 可能在上面的 goroutine 执行 Add 前就返回。

这不是“偶尔少等了一次”这么简单。若调用方在 Wait 返回后关闭结果通道、释放上下文或结束进程，后台任务就可能失去它依赖的资源；如果新的正向 Add 与正在等待计数器归零的 Wait 发生在零值转换点，还可能触发运行时报告的 WaitGroup misuse。即使这次没有复现，也不能把它当成安全调度。

Go 官方的 waitgroup 分析器把“在新 goroutine 内调用 Add”列为典型误用，因为 Wait 可能在新 goroutine 启动前提前返回。真正需要修复的是登记时机，而不是给示例加一个休眠或反复重试。

防护控制：把 Add 固定在启动动作之前

我现在会把“登记”和“启动”写成相邻的两行，减少以后重构时把 Add 移进闭包的机会。循环里尤其要注意把循环变量传入闭包，并让 Done 尽早用 defer 配对。

var wg sync.WaitGroup

for _, id := range ids {
	wg.Add(1) // 计数器为零时，必须在 Wait 之前完成正向 Add。
	go func(id int) {
		defer wg.Done() // 每次 Add(1) 只对应一次 Done。
		process(id)
	}(id)
}

wg.Wait() // 循环结束后再等待这批已登记的任务。

如果项目使用的 Go 版本提供 WaitGroup.Go，也可以让标准库把“登记并启动”放在同一个调用里；但无论采用哪种写法，任务创建边界都应先于等待边界。这里的重点不是追求更短的代码，而是让计数关系在审查时一眼可见。

风险分级：哪些追加是允许的，哪些必须停下来改

这里有一个容易被标题误导的细节：并不是所有“Add 发生在 Wait 之后”都必然是数据竞争。若上一轮 Wait 已经返回，下一轮才开始新的 Add，这是复用 WaitGroup 的正常边界；真正危险的是同一批任务里，计数器为零时让正向 Add 和 Wait 互相看不见。

审计记录：提交前我会复查这份清单

• Add(1) 是否位于创建 goroutine 的语句之前，而不是闭包内部。
• 每个已经登记的任务是否恰好执行一次 Done，并尽量在函数入口用 defer 固定下来。
• Wait 是否只等待一批已完成登记的任务，是否误当成“未来任务注册器”。
• 复用同一个 WaitGroup 时，下一批 Add 是否等到上一批 Wait 返回之后。
• 任务函数是否依赖会在 Wait 返回时被关闭或释放的资源。

# 让 Go 官方分析器检查一部分 WaitGroup 误用模式；这是辅助检查，不替代生命周期设计。
go vet ./...

go vet 能帮助发现简单的“在新 goroutine 内 Add”模式，但它不能替你证明所有动态调度都正确。最终仍要回到任务登记点、等待点和资源释放点，确认三者属于同一批生命周期。

两个容易混淆的问题

把 Wait 放进另一个 goroutine 就能解决吗？ 不能。只要正向 Add 仍可能在计数器为零时与 Wait 并发，等待边界就没有建立。应先完成任务登记，再安排等待。

只启动一个 goroutine 也需要先 Add 吗？ 需要。任务数量不会改变零值时序规则；单个任务同样可能还没来得及执行 Add，调用方的 Wait 就已经返回。

我最后采用的判断方式是：把 WaitGroup 当成已经存在任务的计数契约，而不是未来任务的发现器。只要 Add 先于任务启动、Done 与登记一一对应，Wait 的返回条件就清楚，后续排查也不会被调度时序带偏。