WaitGroup.Add() 必须在启动 goroutine 前调用，若在 goroutine 内部调用会导致漏计数；正确做法是循环中先 wg.Add(1)，再 go func()。

WaitGroup.Add() 在 goroutine 内部调用会漏计数

常见错误是把 Add() 放在 go 启动的函数里，比如：

func badExample() {
    var wg sync.WaitGroup
    for i := 0; i < 5; i++ {
        go func() {
            defer wg.Done()
            wg.Add(1) // ❌ 错误：Add 必须在启动 goroutine 前调用
            time.Sleep(time.Second)
        }()
    }
    wg.Wait() // 可能立即返回，或 panic: negative WaitGroup counter
}

Add() 不是线程安全的“原子增”，它只是修改内部计数器；但更关键的是，WaitGroup 要求 Add() 和 Done() 配对，且 Add() 必须在 Wait() 开始前完成。如果 Add() 晚于 Wait() 执行（例如被调度到后面），就会触发 panic: sync: negative WaitGroup counter。

• 必须在 go 语句之前调用 wg.Add(1)
• 循环中注意闭包捕获变量问题：用 go func(i int) { ... }(i) 或局部变量赋值
• 若数量动态不确定（如从 channel 接收任务），需先收集再统一 Add()，不能边收边启

Done() 调用次数超过 Add() 会导致 panic

每个 Done() 对应一次 Add(1)，多调一次就让计数器变负，运行时直接 panic。

典型场景：

• goroutine 中发生 panic，defer wg.Done() 仍会执行，但若该 goroutine 因重试、重复启动等原因被多次创建，就可能重复 Done()
• 错误地在 if 分支外写 defer wg.Done()，而实际逻辑可能提前 return
• 多个 defer wg.Done() 被重复注册（比如封装函数里又调了一次）

检查方法：用 go vet 无法发现，需人工核对配对；更稳妥的是用 defer + 明确作用域，避免嵌套 defer 或条件性启动。

WaitGroup 复用未重置引发不可预测等待

sync.WaitGroup 不支持复用 —— 一旦 Wait() 返回，内部计数器归零，但结构体本身未被标记为“已结束”。若再次调用 Add()，行为是允许的，但极易出错：

• 忘记在第二次使用前调用 Add()，导致 Wait() 立即返回，后续 goroutine 还在跑
• 第一次 Wait() 尚未返回，就对同一 WaitGroup 实例二次 Add()，造成计数混乱
• 跨函数传递未重置的 WaitGroup 指针，调用方以为它是干净的

正确做法是：每次新任务都用新的 WaitGroup 实例。不要试图“清空”或“重置”它 —— Go 官方明确不提供 Reset 方法，就是防止误用。

WaitGroup 与 context.WithTimeout 组合时超时后仍等待

WaitGroup.Wait() 是阻塞调用，不响应 context 取消。即使你传了 ctx 给 goroutine，主协程仍会在 wg.Wait() 卡死，直到所有 goroutine 自行结束。

例如：

func withTimeoutBad(ctx context.Context) {
    var wg sync.WaitGroup
    wg.Add(1)
    go func() {
        defer wg.Done()
        select {
        case <-time.After(5 * time.Second):
            fmt.Println("work done")
        case <-ctx.Done():
            fmt.Println("canceled")
        }
    }()
    <-ctx.Done() // 假设 2s 后超时
    wg.Wait() // ⚠️ 这里会等满 5s，而不是立即返回
}

解决方式只有两种：

• 不用 WaitGroup，改用 channel + select 等待完成信号（适合少量 goroutine）
• 保留 WaitGroup，但把 Wait() 放进单独 goroutine，用 select 控制超时（注意：需额外 channel 通知完成）

最易忽略的一点：WaitGroup 本身没有上下文感知能力，任何想“中断等待”的需求，都得靠外部机制绕开它 —— 它只负责计数，不负责调度或取消。