Go WaitGroup.Go 怎样组织任务计数

如果一段 Go 代码只是想“启动几项任务，最后等它们都结束”，Go 1.25 的 sync.WaitGroup.Go 可以把任务登记和结束扣减收在一起。调用它会把任务加入 WaitGroup，传入的函数返回后计数自动减少，主协程仍然用 Wait 等待归零。

它解决的主要是 Add(1)、启动 goroutine、defer Done() 三处容易不同步的问题，但不是所有 WaitGroup 都应该立刻改写。下面按我在一组并发任务中采用它时遇到的几个边界，说明怎样组织任务计数。

官方资料：https://pkg.go.dev/sync

版本说明：https://go.dev/doc/go1.25

WaitGroup.Go 到底替代了什么

传统写法把一个任务拆成三个动作：先增加计数，再创建 goroutine，最后在函数退出前调用 Done。只要某条返回路径漏掉 Done，Wait 就可能一直等下去；如果先启动 goroutine 再登记，也会让计数建立得太晚。

WaitGroup.Go 把这组动作封装成一个方法。它适合没有返回值、由 WaitGroup 统一等待的任务。需要注意，官方文档要求传入的函数不能 panic；如果业务需要把异常转成错误，应在函数内部完成恢复和错误记录，而不是把 panic 当成正常的完成信号。

先把模块版本切到 Go 1.25

WaitGroup.Go 是 Go 1.25 新增的标准库方法。项目如果仍按旧版本的 go 指令构建，编辑器或构建机可能找不到该方法；先确认团队的工具链版本，再决定是否迁移。

# 将模块的语言版本声明为 1.25，便于团队统一检查工具链
go mod edit -go=1.25

# 查看当前实际使用的 Go 工具链版本
go version

版本声明只是迁移前提，不会自动改写已有并发代码。旧项目若需要同时支持 Go 1.24 或更早版本，就不能直接在公共代码中调用这个新方法，可以继续使用兼容旧版本的显式 Add/Done 方案，或把新 API 隔离在明确的版本边界中。

用 WaitGroup.Go 组织一组并发任务

最小用法是创建一个 WaitGroup，在循环里为每个任务调用 Go，循环结束后调用 Wait。闭包捕获循环变量时仍然要保持清楚的变量边界，下面显式复制局部变量，方便项目兼容不同的 Go 语言版本。

package main

import (
	"fmt"
	"sync"
)

func main() {
	var wg sync.WaitGroup
	jobs := []string{"图片索引", "日志归档", "缓存预热"}

	for _, job := range jobs {
		job := job // 为每个闭包保存当前任务名称，避免循环变量语义造成误读
		wg.Go(func() {
			// Go 自动登记任务，函数返回时自动减少 WaitGroup 计数。
			fmt.Println("完成：", job)
		})
	}

	// 必须在所有初始任务登记后等待计数归零。
	wg.Wait()
	fmt.Println("所有任务已结束")
}

这段写法的重点不是少写两行，而是让“任务从哪里开始、什么时候算完成”落在同一个函数边界里。业务函数正常返回时，WaitGroup 才会自动减少计数；主协程的 Wait 只负责等待，不负责推测任务数量。

空组和嵌套任务要分清调用时机

第一次使用一个空的 WaitGroup 时，Go 必须发生在 Wait 之前。空组上的 Wait 会立即返回，如果另一个 goroutine 之后才来注册任务，等待方并没有被告知要等这项新任务。

当 WaitGroup 已经有任务未完成时，正在运行的任务可以继续调用 Go 注册子任务。这种方式适合“父任务发现更多工作”的场景，但父任务要在注册子任务后再返回，避免把任务发现动作放到生命周期之外。

package main

import (
	"fmt"
	"sync"
)

func main() {
	var wg sync.WaitGroup

	// 初始任务在 Wait 之前登记，避免空组 Wait 提前返回。
	wg.Go(func() {
		fmt.Println("父任务开始")

		// 当前组仍然非空，可以继续登记由父任务发现的子任务。
		wg.Go(func() {
			fmt.Println("子任务完成")
		})
	})

	// 父任务和它登记的子任务都会被同一个 WaitGroup 等待。
	wg.Wait()
}

如果一个 WaitGroup 被复用于几批互相独立的任务，下一批 Go 应该等上一轮 Wait 返回之后再开始。这样读者可以明确分出每一轮任务的生命周期，也不会把旧任务和新任务误认为同一批。

什么时候仍然使用 Add 和 Done

WaitGroup.Go 的边界是“由它启动一个新的 goroutine，并在函数返回时完成扣减”。如果你要追踪的是已经由别的组件创建的 goroutine、异步回调、外部事件，或者需要把 Done 放在一个不同于函数返回点的生命周期节点，显式 Add/Done 更合适。

package main

import (
	"sync"
)

func startCallbackWorker(wg *sync.WaitGroup, register func(func())) {
	wg.Add(1) // 外部回调尚未触发，计数要先覆盖这段等待生命周期
	register(func() {
		defer wg.Done() // 回调处理结束后再扣减，而不是按启动函数返回判断
		// 处理外部组件回调携带的数据。
	})
}

两种写法的关系可以这样记：任务天然由当前函数包住，并且需要马上开 goroutine，就优先考虑 Go；任务的完成点由外部事件决定，或者需要兼容旧 Go 版本，就使用 Add/Done。

迁移时最容易忽略的三个边界

我的迁移判断

对一组“启动即计数、函数返回即完成”的普通并发任务，WaitGroup.Go 确实更容易读，也减少了 Add/Done 错位的机会。它并没有改变 WaitGroup 的等待模型：Wait 仍然只等待计数归零，错误传播、取消、超时和结果收集仍需由 channel、context 或其他结构单独负责。

因此迁移的顺序可以很小：先把 Go 版本统一到 1.25，再替换边界清楚的 Add/Done 对；遇到外部回调、跨函数生命周期或需要兼容旧工具链的代码，保留显式计数。这样改动的收益是计数责任更集中，而不是把所有并发控制都塞进一个新方法。

相关问题

WaitGroup.Go 能不能返回任务结果？

不能直接返回结果。它只负责启动和等待任务，结果可以通过带缓冲 channel、共享结果数组配合锁，或其他专门的并发抽象传递。

WaitGroup.Go 能不能替代 context？

不能。WaitGroup 只知道任务是否结束，不负责取消、超时和请求范围传播；需要提前停止任务时仍应把 context 传入任务函数。

旧版本 Go 项目能直接编译这段代码吗？

不能假定可以。WaitGroup.Go 从 Go 1.25 开始提供，旧工具链应继续使用 Add/Done 或通过版本隔离来保持兼容。