waitgroup 计数器负值 panic 是硬性越界而非偶发错误，因 add(-1) 或 done() 调用超次会立即触发 panic；其校验在 add 入口即执行，且复用时旧 goroutine 未结束就新 add 亦导致竞态。
WaitGroup 计数器负值 panic 不是偶发错误，而是调用逻辑硬性越界 —— 只要 Add(-1)、Done() 多调一次、或 Add() 没在 Done() 前执行，就必然崩溃。
为什么 Add() 传负数会立刻 panic
Go 运行时在 sync.WaitGroup.Add() 入口就做校验：参数 delta 直接触发 <code>panic("sync: negative waitgroup counter")。这不是延迟报错，也不依赖当前计数器值 —— 即使 wg 还没被用过，wg.Add(-1) 也会当场中断。
- 常见误写：
wg.Add(len(tasks) - i)中i > len(tasks)导致负结果 - 动态计算出错：
wg.Add(expected - actual)，但actual被并发修改且未加锁，算出 -2 - 把
Done()错写成Add(-1)后又保留原Done()，等于减两次
Done() 调用次数超过 Add() 总和必 panic
Done() 就是 Add(-1) 的封装，它不检查“当前是否还有任务在等”，只管减。第 N+1 次调用时，计数器从 0 变成 -1，立刻 panic。
- 典型场景：函数里
defer wg.Done()，但内部有多个return或panic路径，导致defer执行多次 - 分支逻辑漏判：
if err != nil { return }前没defer，但之后又写了wg.Done() - 循环启动 goroutine 却只调一次
Done()，比如在循环外统一go func() { ...; wg.Done() }()
WaitGroup 复用时的隐性竞态陷阱
sync.WaitGroup 支持重用（Wait() 返回后可再 Add()），但前提是上一轮所有 Done() 已执行完毕。问题常出在“旧 goroutine 还没结束，新 Add() 已开始”。
- 结构体字段复用：
type Worker struct { wg sync.WaitGroup }，多个任务共用一个实例，某次Done()实际属于上一轮 - 优雅关闭场景：
gracefulConn.Close()被标准库、中间件、超时逻辑多次调用，每次无条件wg.Done() - 修复关键：用
sync.Once包裹Done()，如w.closed.Do(func() { wg.Done() })，并确保gracefulConn是指针类型
调试负计数 panic 的实际手段
panic 日志只有 sync: negative waitgroup counter，不带位置信息。靠日志或断点定位才有效：
- 所有
Add()和Done()前后加log.Printf("Add(%d) at %s", n, debug.PrintStack())（仅调试） - 禁用异步抢占：
GODEBUG=asyncpreemptoff=1 go run main.go，让 panic 栈更稳定 - 避免“打印当前计数”：WaitGroup 没公开读取接口，任何自定义反射/原子变量辅助计数都需额外同步，容易引入新竞态
- 最可靠方式：静态检查 —— 确保每个
Done()都配defer，且不出现在条件分支的非终态出口中
真正难防的不是语法错误，而是时序错位：Add 和 Done 看似配对，却因 goroutine 启动延迟、Close 多次触发、或跨轮次共享实例，在运行时交错执行。这类问题不会在单元测试里暴露，只在压测或上线后随机炸。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
