Go 语言中 context 树节点的内存泄露排查与预防

先说一个很多人容易忽略的核心判断：Go 语言里 context 树节点本身并不会直接泄漏内存，真正造成泄漏的，是藏在 context.Value 里的大对象，或者是 context.WithCancel 和 WithTimeout 返回的 cancelFunc 被长期持有却不调用——这种情况会把内部 timer、channel 以及闭包变量牢牢钉在堆上，怎么也回收不了。

那具体是怎么泄漏的，又该怎么防？我们来逐个拆解。

为什么 context.Value 不该存大结构体

context.Value 本质上是对 map[interface{}]interface{} 的一层浅封装，但它的生命周期完全由 parent context 决定。换句话说，一旦你把 *bytes.Buffer、[][]byte 或者某个自定义的大结构体塞进 ctx.Value(key, hugeObj)，只要这个 context 还活着——比如 context.Background()，或者 HTTP server 启动时创建的根 context——hugeObj 就永远逃不出 GC 的回收范围。

实际开发中常见的现象是：用 pprof 的 -inuse_space 一看，大量 *bytes.Buffer 或 []uint8 占着高位，调用栈指向 http.serverHandler.ServeHTTP → yourMiddleware → ctx.WithValue，但你自己压根没在 middleware 里显式 new 过这些 buffer。这种时候基本可以断定，是某些依赖库或框架内部把大对象挂到 context 上了。

所以有几个原则值得记住：

• 只存轻量标识：用户 ID、trace ID、request ID 这类字符串或整数就够了，别往里面塞结构体指针。
• 避免嵌套传递：不要在中间层反复 WithValue 构建新 context，最好一次性注入必要的字段。
• 需要警惕的是：context.WithValue(ctx, key, &smallStruct{}) 其实比 context.WithValue(ctx, key, smallStruct{}) 更危险——前者让整个 struct 被强引用住，后者虽然也是传值拷贝，但同样不推荐。

cancelFunc 泄漏：timer 和 channel 被卡住

context.WithCancel 和 context.WithTimeout 返回的 cancel 函数并不是那种“用完即焚”的无状态函数。它内部持有一个未关闭的 chan struct{}，对于 WithTimeout 还额外带了一个没 Stop 的 *time.Timer。如果你把 cancel 存进全局 map、结构体字段，或者作为回调参数丢给第三方库后就不管了，这些资源就会一直挂在那里。

怎么发现这类问题？pprof -goroutine 里能看到大量 runtime.timerproc 或 runtime.selectgo 状态的 goroutine；而 pprof -heap 中 *time.Timer 和 chan struct{} 的实例数会随请求数线性增长，怎么降都降不下来。

几个必须遵守的规矩：

• cancel 函数必须成对调用：有 WithCancel 就得有明确调用点，绝对不能只声明不执行。
• 绝不在结构体中保存 cancel 函数：比如 type Service struct { cancel context.CancelFunc }——这个模式会让 Service 生命周期绑定 cancel，而 cancel 又拖着 timer，一拖就是一串。
• HTTP handler 里启动 goroutine 时，如果用了 ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)，一定要在 handler 返回前调用 cancel()，哪怕是提前 return 也得补上。这不是建议，是铁律。

context.WithValue 配合 defer 导致的隐式长生命周期

很多人写中间件时习惯这么来：

func authMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        user, _ := getUserFromToken(r)
        ctx := context.WithValue(r.Context(), userKey, user)
        r = r.WithContext(ctx)
        defer func() {
            log.Info("request done")
        }()
        next.ServeHTTP(w, r)
    })
}

这样写有什么问题？如果 next 启动了一个后台 goroutine，并且把 r.Context() 传了进去——比如日志上报、异步审计之类——那 user 就会被这个 goroutine 的闭包捕获住，直到 goroutine 结束才能释放。而这个结束时间呢？完全不可控。

应对策略很明确：

• 避免在 defer 作用域外传递 context.Value 数据：所有依赖 value 的逻辑最好在当前 handler 函数内完成。
• 改用显式参数传递：把 user.ID 提取出来，作为参数传给下游函数，而不是塞进 ctx。这样做更安全，也更清晰。
• 如果确实需要跨 goroutine 传递，用 context.WithValue(context.Background(), ...) 构造一个全新的、短生命周期的 context，而不是复用 request context。

如何验证 context 相关泄漏是否已修复

光靠看代码可不行，得用 pprof 抓两次快照做比对。重点不是内存总量，而是看对象存活链路有没有被切断。

• 启动服务后等 1 分钟，执行 curl -s "http://localhost:6060/debug/pprof/heap?debug=1" | grep -E "(heap_inuse|heap_objects)"，先记下 baseline。
• 然后发 100 次请求，再等 30 秒，抓第二次 heap。对比 heap_objects 的增量是否回落——如果一直不掉，说明有对象没被 GC 认领。
• 用 go tool pprof -http=:8080 your_binary heap.pb.gz，在 Web UI 中 Focus 输入 *time.Timer 或你怀疑的结构体名，看看 Call graph 是否还指向 context.WithTimeout 或 context.WithValue。
• 可以给关键结构体加 runtime.SetFinalizer 做调试用途——如果 finalizer 从来不触发，说明它依然被 context 树的某处强引用着。

最后说一个最容易忽略的点：context 泄漏往往不会表现为内存暴涨，而是“稳定缓慢上涨 + 大量 timer/goroutine 堆积”。每个泄漏的 cancelFunc 虽然只占几 KB，但几百个累积下来，就足以把服务拖垮。所以这类问题，发现得越早，代价越小。