传 *sync.WaitGroup 必须是指针，因值传递会导致主协程与子协程操作不同副本，使 Wait() 卡死或 panic；Add() 必须在 goroutine 启动前调用，且需确保实例生命周期覆盖所有 Done() 调用。
传 *sync.WaitGroup 必须是指针，不是值
Go 里所有函数参数都是值传递，sync.WaitGroup 是一个包含 mutex 和 counter 的结构体，如果传值，调用方和被调函数操作的是两个独立副本——Add() 在子 goroutine 里调了，主 goroutine 的 Wait() 永远等不到归零。
常见错误现象：Wait() 卡死、程序不退出、或 panic “WaitGroup is reused before previous Wait has returned”（因为多个副本各自调了 Wait()）。
- 正确写法：函数签名里写
wg *sync.WaitGroup，调用时传&wg - 错误写法：
wg sync.WaitGroup或func do(wg sync.WaitGroup) - 即使函数只调
Done()，也必须传指针——Done()修改的是原结构体里的 counter 字段
WaitGroup.Add() 必须在启动 goroutine 前调用
Add() 不是线程安全的，不能在 goroutine 内部调；它得在 go 语句之前执行，否则存在竞态：可能 Wait() 已开始等待，但 Add() 还没执行，导致计数器初始为 0，Wait() 直接返回。
使用场景：批量启 goroutine 处理任务，比如并发请求、文件处理、管道消费。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- ✅ 正确：
wg.Add(1); go func() { defer wg.Done(); ... }() - ❌ 错误：
go func() { wg.Add(1); defer wg.Done(); ... }() - 如果数量动态，先算好数量再统一
Add(n)，别在循环里边启边Add()
别把 *sync.WaitGroup 和闭包变量混用导致提前释放
当在循环中启动多个 goroutine 并传入同一个 *sync.WaitGroup 时，容易忽略闭包捕获变量的问题——但这里真正危险的是：如果 WaitGroup 本身生命周期短于 goroutine，比如它是个局部变量而 goroutine 异步执行，就可能访问已释放内存（虽 Go GC 通常兜底，但逻辑上已失控）。
性能影响：无直接开销，但逻辑错乱会导致 goroutine 泄漏或提前结束。
- 确保
WaitGroup实例的生命周期覆盖所有Done()调用，通常定义在函数顶部或作为结构体字段 - 避免在 defer 中对
WaitGroup做非原子操作（比如defer wg.Add(-1)），这不等价于Done()，且不是线程安全的 - 不要用
WaitGroup控制“谁来调Done()”，而是明确由每个 goroutine 自己负责，哪怕它 panic 了也要defer wg.Done()
替代方案：什么情况下不该用 *sync.WaitGroup 传参
WaitGroup 本质是同步原语，不是任务分发机制。如果函数需要知道“我属于哪个组”“我该不该做某事”，说明职责已经越界——这时候应该用 channel 控制流程，或用 context.Context 传递取消信号。
容易踩的坑：把 WaitGroup 当上下文传，结果某个分支忘了 Done()，整个流程卡死；或者在 error path 里漏掉 Done()，导致计数器永远不归零。
- error 处理路径必须显式
defer wg.Done()，或在每个 return 前调用 - 如果函数要支持取消，优先用
context.Context+select，而不是靠WaitGroup等待“可能永远不会来的 Done” - 测试时注意：
WaitGroup无法重用，测试 case 之间要新建实例，否则 panic
最常被忽略的一点：WaitGroup 的 zero value 是可用的，但一旦调过 Wait()，就不能再 Add()；很多人在重试逻辑里反复用同一个实例，却没重置，结果 panic。
