1. 理解sync.WaitGroup的基本机制
在Go语言的并发编程中，sync.WaitGroup是一个简单而强大的同步原语。它主要用于等待一组goroutine完成工作，特别适合"分而治之"的任务场景。WaitGroup内部维护着一个计数器，这个计数器的值代表了需要等待的goroutine数量。
WaitGroup的核心方法有三个：
- Add(delta int)：增加或减少等待的goroutine数量
- Done()：相当于Add(-1)
- Wait()：阻塞直到计数器归零
乍看之下这个机制非常简单，但在实际使用中，Add方法的调用位置却隐藏着许多微妙的陷阱。很多开发者在初次接触时，往往会忽略调用位置的时序问题，导致程序出现难以追踪的竞态条件或死锁。
关键点：WaitGroup的Add方法必须在启动goroutine之前调用，这是保证并发安全的最基本前提。
2. Add方法调用位置的典型陷阱
2.1 在goroutine内部调用Add
这是一个最常见的错误模式：
go复制var wg sync.WaitGroup
for i := 0; i < 10; i++ {
go func() {
wg.Add(1) // 错误：在goroutine内部调用Add
defer wg.Done()
// 工作代码...
}()
}
wg.Wait()
这种写法的问题在于，goroutine的调度是不确定的。当主goroutine执行到wg.Wait()时，可能还没有任何工作goroutine执行到wg.Add(1)，导致Wait立即返回，而实际上工作还没开始。
2.2 Add调用与goroutine启动之间的竞态
即使Add调用在goroutine外部，如果位置不当也会有问题：
go复制var wg sync.WaitGroup
wg.Add(1) // 正确但不够安全
go func() {
defer wg.Done()
// 工作代码...
}()
// 这里可能有其他代码
wg.Wait()
这种情况下，虽然Add在goroutine之前调用，但如果"其他代码"执行时间较长，goroutine可能在Add调用前就已经完成并调用了Done，导致计数器变为负数而panic。
3. 正确的Add方法调用模式
3.1 批量Add模式
最安全的做法是在启动所有goroutine之前，一次性Add所需的数量：
go复制var wg sync.WaitGroup
const workerCount = 10
wg.Add(workerCount) // 在循环前一次性Add
for i := 0; i < workerCount; i++ {
go func() {
defer wg.Done()
// 工作代码...
}()
}
wg.Wait()
这种模式完全避免了竞态条件，因为：
- Add调用在所有goroutine启动之前完成
- 计数器设置与goroutine启动是原子性的
- 没有中间代码可能干扰Add和goroutine启动的顺序
3.2 循环内Add模式（带同步）
如果无法预先知道goroutine数量，可以在循环内Add，但必须确保Add和goroutine启动是同步的：
go复制var wg sync.WaitGroup
for _, item := range items {
wg.Add(1) // 在启动goroutine前立即Add
go func(item Item) {
defer wg.Done()
// 处理item...
}(item)
}
wg.Wait()
这种模式的关键是Add和go语句之间不能插入任何可能阻塞的代码，确保goroutine启动紧跟在Add之后。
4. 实际案例分析与调试技巧
4.1 竞态条件检测
Go的竞态检测器可以帮助发现WaitGroup使用中的问题：
bash复制go run -race your_program.go
如果看到关于sync.WaitGroup的竞态警告，很可能是Add调用位置不当导致的。
4.2 计数器为负的panic分析
当看到"negative WaitGroup counter"的panic时，通常意味着：
- Done调用次数多于Add调用
- Add调用太晚，goroutine已经完成
- 重复使用了WaitGroup而没有等待完成
调试这种问题时，可以在每个Add和Done调用处添加日志：
go复制log.Printf("Add: %d", delta)
wg.Add(delta)
// 在Done处
defer func() {
log.Println("Done")
wg.Done()
}()
5. 高级使用场景与最佳实践
5.1 嵌套WaitGroup的使用
在复杂并发场景中，可能需要嵌套使用WaitGroup：
go复制func processBatch(items []Item) {
var batchWg, itemWg sync.WaitGroup
batchWg.Add(len(items))
for _, item := range items {
itemWg.Add(1) // 正确：在启动goroutine前立即Add
go func(i Item) {
defer batchWg.Done()
defer itemWg.Done()
// 处理item...
}(item)
}
itemWg.Wait() // 等待所有item处理完成
batchWg.Wait() // 等待所有goroutine完成
}
5.2 与context配合使用
WaitGroup常与context一起使用来实现超时控制：
go复制func worker(ctx context.Context, wg *sync.WaitGroup) {
defer wg.Done()
select {
case <-ctx.Done():
return
case <-time.After(workDuration):
// 正常工作...
}
}
func main() {
ctx, cancel := context.WithTimeout(context.Background(), timeout)
defer cancel()
var wg sync.WaitGroup
wg.Add(workerCount)
for i := 0; i < workerCount; i++ {
go worker(ctx, &wg)
}
// 等待所有worker完成或超时
done := make(chan struct{})
go func() {
wg.Wait()
close(done)
}()
select {
case <-done:
// 所有worker正常完成
case <-ctx.Done():
// 超时，部分worker可能仍在运行
}
}
6. 性能考量与替代方案
6.1 WaitGroup的性能特点
WaitGroup的实现非常高效：
- 在无竞争情况下使用原子操作
- 在有竞争时才会使用互斥锁
- 内存占用极小
但在超高并发场景下（数万个goroutine），频繁的Add/Done调用可能成为瓶颈。
6.2 替代方案：errgroup
对于需要错误传播的场景，可以考虑使用golang.org/x/sync/errgroup：
go复制g, ctx := errgroup.WithContext(context.Background())
for i := 0; i < 10; i++ {
g.Go(func() error {
// 工作代码...
return nil // 或error
})
}
if err := g.Wait(); err != nil {
// 处理错误
}
errgroup内部也使用WaitGroup，但提供了更高级的错误处理机制。
7. 常见问题解答
7.1 为什么不能把Add放在goroutine内部？
因为goroutine的启动和执行是异步的。主goroutine可能在子goroutine调用Add之前就执行了Wait，导致Wait立即返回，而实际工作还未开始。
7.2 可以重复使用WaitGroup吗？
可以，但必须确保前一次Wait已经返回，并且计数器已经归零。最好在使用前重置WaitGroup的状态。
7.3 Add的参数可以是负数吗？
可以，但不推荐。使用负数参数容易导致计数器混乱，最好使用Done()来减少计数器。
7.4 如何避免忘记调用Done？
总是使用defer来调用Done：
go复制wg.Add(1)
go func() {
defer wg.Done() // 确保一定会执行
// 工作代码...
}()
8. 实战经验分享
在实际项目中，我总结了以下WaitGroup使用经验：
-
命名明确：不要使用简短的wg，而是使用描述性名称如downloadWg、processWg等，提高代码可读性。
-
封装使用：对于复杂逻辑，考虑封装WaitGroup的使用：
go复制type WorkerPool struct {
wg sync.WaitGroup
// 其他字段...
}
func (p *WorkerPool) Start(f func()) {
p.wg.Add(1)
go func() {
defer p.wg.Done()
f()
}()
}
func (p *WorkerPool) Wait() {
p.wg.Wait()
}
- 与channel配合：WaitGroup常与channel配合使用，实现更复杂的并发模式：
go复制func parallelProcess(items []Item) []Result {
var wg sync.WaitGroup
results := make(chan Result, len(items))
wg.Add(len(items))
for _, item := range items {
go func(i Item) {
defer wg.Done()
results <- processItem(i)
}(item)
}
go func() {
wg.Wait()
close(results)
}()
var collected []Result
for r := range results {
collected = append(collected, r)
}
return collected
}
-
避免过度使用：不是所有并发场景都需要WaitGroup。对于简单的"发射后不管"任务，可以直接启动goroutine而不需要等待。
-
测试中的使用：在测试并发代码时，WaitGroup可以帮助确保所有goroutine都已完成：
go复制func TestConcurrent(t *testing.T) {
var wg sync.WaitGroup
var counter int
wg.Add(100)
for i := 0; i < 100; i++ {
go func() {
defer wg.Done()
atomic.AddInt32(&counter, 1)
}()
}
wg.Wait()
if counter != 100 {
t.Errorf("counter = %d, want 100", counter)
}
}
通过遵循这些实践，可以避免大多数WaitGroup相关的并发问题，写出更健壮的Go并发代码。