Go sync.WaitGroup让计数与 goroutine 启动配对的写法

在 Go 中用 sync.WaitGroup 等待一批 goroutine，最稳的配对规则只有一句话：每启动一个任务，就在执行 go 之前调用一次 Add(1)；每个任务入口立刻用 defer wg.Done() 归还计数；所有任务提交后，主流程再调用 Wait()。这样计数代表“尚未完成的任务数”，而不是模糊的 goroutine 数量。

先把任务计数和启动动作绑在一起

如果任务来自一个切片，最容易读懂的方式是把 Add 紧挨着 go 写。计数来源是待处理元素，不是某个瞬间恰好存在的 goroutine 数量。

package main

import (
    "fmt"
    "sync"
)

func processAll(items []string) {
    var wg sync.WaitGroup
    for _, item := range items {
        wg.Add(1) // 先登记一个任务，再允许 goroutine 启动
        go func(item string) {
            defer wg.Done() // 无论正常返回还是提前 return，都归还计数
            fmt.Println("processing:", item)
        }(item)
    }
    wg.Wait() // 所有任务都提交后，等待计数归零
}

这个例子只保证 processAll 返回时任务函数已经结束，不保证输出顺序，也不保证多个任务之间的业务数据安全。共享切片、map 或结果集合仍需单独设计同步方式。

Done 为什么应该放在任务入口

Done 的语义是“这个任务已经结束”，所以它应覆盖整个函数体，而不是只放在最后一行。函数中只要有多个 return，手写 wg.Done() 就很容易漏掉某个分支；defer 可以把释放动作绑定到函数生命周期。

func handle(item string, wg *sync.WaitGroup) {
    defer wg.Done() // 先建立退出保障，再处理输入
    if item == "" {
        return // 空任务也会执行上面的 Done
    }
    if item == "skip" {
        return // 其他提前返回同样不会遗留计数
    }
    fmt.Println("handled:", item)
}

传入的是 *sync.WaitGroup，而不是值。WaitGroup 包含并发状态，官方文档明确要求这类值不要复制；把它作为值参数传入会让调用方和任务操作不同的副本，等待结果就失去意义。

Wait 放在提交阶段之后

主流程要先完成一轮“登记并启动”，再进入等待。如果把 Wait 放在循环内部，第一项可能尚未结束，后续任务就无法按预期提交；如果把 Add 放到 goroutine 内部，主流程可能先执行 Wait，从而在计数尚未建立时提前通过。

可以按下面的顺序检查：第一，Add(1) 是否位于 go 之前；第二，每条任务路径是否都会经过 defer；第三，Wait 是否只出现在全部任务启动之后；第四，是否存在复制 WaitGroup 或在一轮等待期间继续混用计数的代码。

把配对规则收敛成可复用的批处理函数

实际项目里可以让一个函数负责创建 WaitGroup、提交任务和等待完成，把边界固定下来。若任务需要返回错误，另行使用结果通道或错误组；不要把 WaitGroup 当成错误收集器。

func runBatch(items []string) {
    var wg sync.WaitGroup
    for _, item := range items {
        item := item // 明确为当前迭代保存任务输入
        wg.Add(1)   // 计数与下面这次 goroutine 启动一一对应
        go func() {
            defer wg.Done() // 任务结束时自动归还计数
            handle(item, &wg) // 示例中 handle 仅代表具体业务处理
        }()
    }
    wg.Wait() // 只在全部 goroutine 提交后等待
}

示例突出的是生命周期配对；工程代码不要让 handle 再次调用同一个 Done，否则会重复归还。若使用 Go 1.22 及以上的循环变量语义，仍建议让输入边界清楚；关键不是依赖语法细节，而是每个 goroutine 都拿到与其任务对应的数据。

常见问题

为什么 Add 不能写进 goroutine？

因为 Wait 可能先于异步函数执行，计数还没有建立就被观察为零。把 Add 放在启动语句之前，才能让等待边界覆盖这次任务。

WaitGroup 能不能复用？

可以在一轮计数归零后重新使用，但不要在同一轮 Wait 进行期间随意增加新任务；更清晰的做法是让每个批处理阶段拥有明确的提交和等待边界。

归根结底，sync.WaitGroup 的可靠性来自三件事的一致顺序：先登记、再启动，任务入口确保 Done，最后统一 Wait。只要这条配对关系在代码结构上可见，goroutine 数量变化也不会破坏主流程的收敛。