Go 1.25 go vet 实战：把 WaitGroup 和 HostPort 坑挡在 CI 里

Go 1.25 的新特性里，有些看起来不“酷”，但对团队质量很有用。比如 go vet 新增的两个检查：waitgroup 和 hostport。

一个盯并发里 WaitGroup.Add 的位置，一个盯网络地址拼接。它们都不是高深问题，但特别容易在线上变成烦人的事故：偶发等待不完整、IPv6 环境连不上、CI 没拦住，最后排查半天。

这篇按工程落地讲：这两个 analyzer 到底抓什么，怎么修，怎么放进 CI，以及团队里怎么处理误报和历史债。

为什么这两个检查值得单独说

我一直觉得，静态检查最有价值的地方不是“显得规范”，而是把人容易手滑的点变成机器拦截。WaitGroup.Add 和地址拼接正好都是这种问题。

WaitGroup 的 bug 往往不是本地必现，而是高并发时偶尔出现。host:port 拼接看起来更简单，直到遇到 IPv6、空 host、带方括号地址、或者跨平台网络配置，才发现字符串拼接不靠谱。

Go 1.25 把这些检查放进 go vet，对团队来说就是一个机会：别再靠 code review 瞪眼睛找，把它放进 CI。

waitgroup 检查：Add 别写进 goroutine

先看典型问题：

var wg sync.WaitGroup

for _, job := range jobs {
    go func(job Job) {
        wg.Add(1)
        defer wg.Done()
        handle(job)
    }(job)
}

wg.Wait()

这段代码的问题在于：Add(1) 发生在新 goroutine 里，主 goroutine 可能先执行到 Wait()。如果这时计数还没加上，Wait() 就可能提前返回。

正确写法是先加计数，再启动 goroutine：

var wg sync.WaitGroup

for _, job := range jobs {
    wg.Add(1)
    go func(job Job) {
        defer wg.Done()
        handle(job)
    }(job)
}

wg.Wait()

如果你已经升级到 Go 1.25，也可以按场景考虑 WaitGroup.Go，但前提是你不需要错误返回和取消传播。

hostport 检查：别手拼 host:port

再看另一个很常见的写法：

addr := host + ":" + port
ln, err := net.Listen("tcp", addr)

如果 host 是 127.0.0.1，这看起来没问题。但如果 host 是 IPv6，比如 ::1，正确地址应该是 [::1]:8080。手拼字符串很容易出错。

更稳的写法是：

addr := net.JoinHostPort(host, port)
ln, err := net.Listen("tcp", addr)

解析时也别自己切字符串：

host, port, err := net.SplitHostPort(addr)
if err != nil {
    return err
}

这类代码平时很少被注意，但一旦服务要支持 IPv6、容器网络、代理地址、双栈环境，就会变成线上兼容性问题。

怎么在项目里跑

最基本的命令就是：

go vet ./...

CI 里我建议先单独加一个 job，不要混在单测日志里。这样失败时开发能第一眼看出是静态检查失败，而不是测试失败。

steps:
  - name: go vet
    run: go vet ./...

如果你们仓库很大，历史问题很多，不要一口气全量阻断所有分支。可以先对新增代码和核心包启用，再逐步扩大范围。

落地时别忽略老代码

很多团队加静态检查会卡在历史包袱：一跑 go vet ./...，红一片。于是大家干脆关掉。这就可惜了。

我更建议分三步：

• 第一步，统计现有问题，先不要阻断 CI。
• 第二步，给核心服务和新改动目录启用阻断。
• 第三步，把历史问题按模块拆小任务清掉。

这样不会把所有人卡死，也能让规则真正留下来。

如何处理误报

任何静态检查都可能有误报，关键是别让误报变成“大家都忽略”。我的习惯是：能改代码就改代码，不能改就写清楚原因，并把绕过控制在最小范围。

比如某段 host 拼接不是给网络库用，而是日志展示，那就把变量名和上下文写清楚，避免 analyzer 或 reviewer 误判。对于 WaitGroup，如果你有特别复杂的封装，最好把并发生命周期收敛到一个小函数里，而不是在业务代码里到处解释。

和 WaitGroup.Go 的关系

前面我写过 WaitGroup.Go。它和这次的 go vet waitgroup 不是一回事，但目标有点像：减少 WaitGroup 模板代码里的手滑。

go vet 是发现错误模式；WaitGroup.Go 是提供更少出错的写法。简单等待型 goroutine 可以考虑 WaitGroup.Go，需要错误返回和取消就继续用 errgroup。

CI 门禁怎么设计更舒服

我不建议把所有质量工具揉成一个大命令。更好的结构是：

• go test ./... 负责行为正确性。
• go vet ./... 负责 Go 官方静态检查。
• 自定义 lint 负责团队风格和业务规范。
• 每个 job 单独输出日志，失败原因一眼能看懂。

这样开发不会因为一个 lint 失败去翻几千行测试日志，体验会好很多。

我的 review 清单

• 所有 WaitGroup.Add 是否在启动 goroutine 前完成。
• 需要错误传播的并发逻辑是否误用了 WaitGroup。
• 网络地址是否使用 net.JoinHostPort 和 net.SplitHostPort。
• CI 是否单独执行 go vet ./...。
• 新增检查是否有渐进启用策略，而不是一开就卡死全仓库。
• 误报是否有记录和最小范围绕过。

最后说句实在话

go vet 的价值不在于“让代码看起来更规矩”，而在于它能把一类线上难排查的问题提前变成 PR 里的红叉。这个红叉越早出现，成本越低。

Go 1.25 的 waitgroup 和 hostport 检查都很朴素，但非常工程化。把它们接进 CI，清掉历史问题，再把规则写进团队规范，你会少掉一些很无聊但很费时间的线上排障。