Go vet waitgroupgo 怎样在发现 WaitGroup 启动问题（输入边界）

如果你在 Go 1.27 的工具链说明里看到 waitgroupgo，先不要把它直接当成一个“给 go vet 加参数”的检查项。它更接近 go fix 里的现代化分析器：面对规则明确的 WaitGroup.Add(1)、go 和 Done 组合，尝试给出 WaitGroup.Go 的迁移建议。真正要排查“启动 goroutine 后才 Add，导致 Wait 可能提前返回”的问题，应先看静态检查提示和代码结构，再决定是否迁移。

结论：先用 go vet ./... 做项目级检查，再用 go fix -diff ./... 观察 waitgroupgo 能否识别出可迁移模式。只有闭包生命周期、参数传递和错误处理都符合预期时，才接受自动改写。

先分清 waitgroupgo 与 go vet 的入口

Go 1.27 的发布说明提到，原有的 waitgroup 分析器改名为 waitgroupgo，目的是避免名称歧义；同一组工具变化还把它描述为将传统的 Add(1)、启动 goroutine、Done 组合现代化为 wg.Go。实际操作时可以把两个命令分成两步：

# 先运行项目级静态检查，观察是否有 WaitGroup 使用风险
go vet ./...

# 只查看现代化分析器可能产生的改动，不直接覆盖源文件
go fix -diff ./...

前一条命令的重点是报告问题，后一条命令的重点是展示可机械迁移的差异。不要因为 go fix -diff 没有输出，就推断代码一定没有并发问题；也不要因为 go vet 没有报错，就把所有 WaitGroup 代码都交给自动改写。

问题现场：Add 放进新 goroutine

下面这种写法把计数增加动作放在新 goroutine 内。主 goroutine 可能先执行到 Wait，此时计数仍然是零，Wait 有机会直接返回，随后子 goroutine 才调用 Add(1)。

package main

import (
	"fmt"
	"sync"
)

func wrongStart() {
	var wg sync.WaitGroup

	go func() {
		// 错误边界：新 goroutine 可能还没有执行到 Add，Wait 就已返回。
		wg.Add(1)
		defer wg.Done()
		fmt.Println("worker finished")
	}()

	// 这里不能证明 worker 已经完成，甚至可能先于 Add 返回。
	wg.Wait()
}

官方分析器针对的是这种“新 goroutine 的第一段语句就是 WaitGroup.Add”的简单形状。它不是完整的并发证明器：如果 Add 被包装进其他函数、由条件分支控制，或计数与多个生命周期交织，静态工具都可能无法替你作出完整判断。

先修复启动顺序，再考虑 WaitGroup.Go

迁移的第一步不是改 API，而是把计数增加放回启动 goroutine 之前。这样 Wait 看到的计数先于并发启动建立，生命周期关系更直观。

func legacyStart() {
	var wg sync.WaitGroup

	// 先登记一个任务，再把任务交给 goroutine 执行。
	wg.Add(1)
	go func() {
		// defer 保证正常返回路径会减少计数。
		defer wg.Done()
		fmt.Println("worker finished")
	}()

	// 只有计数归零后才继续。
	wg.Wait()
}

在支持 WaitGroup.Go 的工具链中，这类单纯的启动模式可以进一步写成：

func modernStart() {
	var wg sync.WaitGroup

	// Go 同时完成计数登记、goroutine 启动和返回时的 Done。
	wg.Go(func() {
		fmt.Println("worker finished")
	})

	// 等待 Go 注册的任务完成。
	wg.Wait()
}

waitgroupgo 适合识别这类结构化模式，因为替换前后的任务边界相对清楚。它的价值在于减少漏写 Done 或把 Add 放错位置的机会，而不是替你重新设计任务调度。

四个不能直接接受自动改写的边界

第一，闭包需要参数时先固定变量。如果循环变量、指针或共享切片会在 goroutine 中继续变化，先确认闭包捕获语义，再决定是否改成 wg.Go。自动替换并不会替你修复数据竞争。

第二，错误处理不应被隐藏。WaitGroup 只负责等待，不负责收集错误。原代码如果通过 channel、errgroup 或结果数组传递失败信息，迁移后仍要保留那条错误通路。

第三，递归或嵌套启动要单独看。如果一个任务在自身执行期间继续调用 wg.Go，要确认这些新任务的加入时机不会与等待阶段形成新的生命周期约束。自动化工具通常只处理局部的固定模式。

第四，不能把“能改写”当成“能证明正确”。分析器可能只覆盖语法和类型关系清晰的代码。涉及超时、取消、共享状态或多个 Wait 调用时，仍然要回到业务生命周期检查。

用差异预览和测试完成复查

实际迁移时，建议先保存工作区，再只看差异。没有差异时说明工具没有找到可自动迁移的模式，不代表项目没有 WaitGroup 风险。

# 查看候选现代化改动，不直接写回文件
go fix -diff ./...

# 接受改动后重新格式化并检查整个模块
gofmt -w .
go vet ./...
go test ./...

如果项目仍需要兼容不支持 WaitGroup.Go 的旧工具链，先确认 go.mod 的语言版本、构建环境和 CI 镜像，再决定是否提交迁移。把新 API 提前写入旧版本构建链，会把并发整理问题变成编译兼容问题。

一张表记住选择顺序

相关问题

waitgroupgo 是 go vet 的独立参数吗？不应这样理解。Go 1.27 的官方说明把它放在工具现代化语境中，使用时应先看对应工具链的帮助和差异输出。

go vet 没有提示，还需要检查 WaitGroup 吗？需要。静态分析覆盖的是明确模式，复杂封装、共享状态和取消逻辑仍要靠代码审查与测试确认。

所有 Add、go、Done 都能改成 wg.Go 吗？不能。只有任务边界清楚、闭包捕获安全、错误通路和工具链版本都满足条件时，才适合迁移。

参考资料：https://go.dev/doc/go1.27；https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/waitgroup；https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/modernize。