Go sync.WaitGroup 如何用计数快照避免 Add 竞态

我在把一批文件任务改成并发处理时，最容易忽略的不是 Done，而是“这一轮到底有多少任务”。如果把 Add(1) 写进新 goroutine，外层又马上调用 Wait，计数器可能还没有增加，Wait 就先返回了。解决办法是先建立一个计数快照：在启动 goroutine 前，把当前已知任务数一次性加入 sync.WaitGroup；goroutine 内只做工作，并用 defer wg.Done() 归还计数。

先把动态任务集合变成计数快照

这里的“快照”不是复制任务内容，而是在某个明确边界上记录数量。比如本轮扫描得到 3 个文件，就先执行 wg.Add(3)，再创建 3 个 goroutine。这样 Wait 看到的是一个已经存在的正计数，而不是等待另一个 goroutine 恰好抢先执行。

package main

import (
    "fmt"
    "sync"
)

func processFiles(files []string) {
    var wg sync.WaitGroup
    wg.Add(len(files)) // 先固定本轮任务数，避免 Add 与 Wait 竞争

    for _, file := range files {
        file := file // 为每个 goroutine 固定当前循环值
        go func() {
            defer wg.Done() // 无论后续分支如何返回，都归还一个计数
            fmt.Println("处理", file)
        }()
    }

    wg.Wait() // 只有快照中的任务全部 Done 后才返回
}

如果 files 为空，Add(0) 后的 Wait 会立即返回，这是正确的空批次结果。真正危险的是计数器仍为零时，另一个 goroutine 才开始执行正数 Add。

为什么把 Add 放进 goroutine 会失去边界

下面的写法看起来像“启动一个任务再登记一个任务”，但登记动作和等待动作没有顺序保证：

var wg sync.WaitGroup
go func() {
    wg.Add(1) // 错误边界：新 goroutine 可能尚未运行
    defer wg.Done()
    doWork()
}()
wg.Wait() // 计数仍为零时可能直接返回

官方 sync.WaitGroup.Add 文档给出的边界是：当计数器为零时，正数 Add 必须发生在 Wait 之前；计数器大于零时，追加正数任务可以发生在运行期间。因此，“动态”并不等于“随时从任意 goroutine Add”，而是要保证追加时旧计数还没有归零。

任务会继续派生时，怎样保存计数边界

如果一个工作 goroutine 会发现子任务，最稳妥的做法是让它在自己的计数仍然有效时登记子任务，并保证父任务不会先 Done 到零。更复杂的生产者场景，我更愿意把“发现任务”和“执行任务”拆开：由一个调度器收集任务，关闭任务队列后再由固定 worker 消费，最后等待 worker 退出。

在 Go 1.25 及以上，也可以使用 WaitGroup.Go：

var wg sync.WaitGroup
for _, file := range files {
    file := file
    wg.Go(func() {
        // Go 负责登记和归还计数；函数体不要 panic
        fmt.Println("处理", file)
    })
}
wg.Wait()

WaitGroup.Go 不能替代任务边界设计：WaitGroup 为空时，仍应在 Wait 前调用它；传入的函数也不能 panic。旧版本 Go 则继续使用“先 Add、再 go、最后 Done”的显式写法。

常见问题

只把 Done 放在成功分支可以吗？

不可以。应该在 goroutine 开头用 defer wg.Done()，否则错误返回或提前分支会让计数器永久大于零。

Wait 返回后还能继续 Add 吗？

只有下一轮独立等待已经开始、并且新的正数 Add 发生在下一次 Wait 之前才安全。不要把它当成同一轮的延迟补登记。

并发数量也要限制时怎么办？

WaitGroup 只负责等待，不负责限流。可以配合带缓冲 channel 或 worker pool 限制同时运行的任务数。

记住一句话：先确定谁属于这一轮，再建立计数；任务可以动态执行，但不能让“首次 Add”和“Wait”在零计数上争抢。