为 HTTP 服务建立 goroutine 泄漏基线与差异对比

如果 HTTP 服务的 goroutine 数量只在高峰期上升，不能马上把增长判定为泄漏；真正需要关注的是请求结束后仍永久阻塞在 channel、sync.Mutex 或其他同步原语上的 goroutine。Go 1.27 提供了 goroutineleak profile，可以把这类阻塞路径从普通 goroutine 数量中分离出来，适合建立可重复的排查基线。

本文的做法是：先固定请求场景，采集一份基线；再让同一场景重复运行，比较 profile 中的阻塞函数和数量；修复退出路径后再次采集。官方文档：

官方文档：https://pkg.go.dev/net/http/pprof；https://pkg.go.dev/runtime/pprof

先分清暂时阻塞与 goroutine 泄漏

goroutine 在等待网络、文件或队列时，短时间处于阻塞状态并不等于泄漏。可以把它视为泄漏的情况是：解除阻塞所需的条件永远不会发生，调用路径也已经结束。比如父函数遇到错误提前返回，worker 仍向一个没人接收的无缓冲 channel 发送结果。

goroutineleak profile 主要覆盖 channel 发送与接收、没有 default 的阻塞式 select，以及 sync 包中的部分同步原语。它不负责判断所有网络 I/O 阻塞，也不能替代测试中的 goroutine 泄漏检查。因此基线应记录“请求场景、采集时刻、profile 类型和重点函数”，不要只记录一个 goroutine 总数。

为 HTTP 服务接入 pprof 采集入口

如果服务已经使用标准库的 net/http/pprof，运行时会注册 profile handler，其中包括 /debug/pprof/goroutineleak。下面用独立监听地址演示接入方式，生产环境还应把该监听器放在受控网络或认证代理之后。

package main

import (
    "log"
    "net/http"
    _ "net/http/pprof" // 注册标准 pprof handler，包括 goroutineleak
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusNoContent)
    })

    // 调试端口与业务端口分开，避免把 profile 暴露给普通业务流量。
    go func() {
        if err := http.ListenAndServe("127.0.0.1:6060", nil); err != nil {
            log.Printf("pprof server stopped: %v", err)
        }
    }()

    // 业务服务使用自己的 mux，便于测试时固定请求入口。
    if err := http.ListenAndServe(":8080", mux); err != nil {
        log.Fatal(err)
    }
}

这里的空白导入只负责注册 handler，不会把业务路由自动改成 pprof 路由。采集地址可以是：

# 只读取 profile 文件，不把响应当作文章中的运行证明。
curl http://127.0.0.1:6060/debug/pprof/goroutineleak > baseline.prof

# 使用 pprof 查看函数维度的阻塞位置。
go tool pprof baseline.prof

固定场景后采集第一份基线

基线的关键不是“第一次采到多少”，而是之后能否复现同一条件。建议为一轮采集固定三件事：相同的请求路径和并发量、相同的等待时间、相同的 profile 命名方式。先让服务完成启动，再执行一轮稳定流量，最后在请求结束后采集。

一个容易产生泄漏的业务形态如下。worker 将结果发送到无缓冲 channel；调用方一旦遇到错误就返回，后续 worker 永远等不到接收者。

type result struct {
    value int
    err   error
}

func processBatch(items []int) ([]int, error) {
    resultsCh := make(chan result) // 无缓冲通道要求发送与接收同时发生
    for _, item := range items {
        go func(item int) {
            value, err := process(item)
            // 调用方提前返回后，这个发送可能永久阻塞。
            resultsCh 

在固定场景中重复调用几轮后，分别保存 profile，例如 baseline-01.prof、baseline-02.prof。基线记录中至少写下采集时间、请求场景、并发规模和重点函数，这样数量变化才有解释依据。

用差异对比定位阻塞路径

进入 pprof 后，先关注类型为 goroutineleak 的结果，再按业务函数查看调用位置。如果多轮采集中同一个发送表达式的数量单调增加，且请求已经结束，通常说明发送端的生命周期没有和接收端对齐。普通 goroutine profile 只能告诉你“有多少”，泄漏 profile 更适合回答“哪些阻塞操作持续留下来”。

比较时不要把所有新增节点都当成 bug：高并发下短暂等待可能在采集时刻存在；真正有价值的是固定场景下持续出现、随轮次增长、并且调用路径已经退出的节点。

# 每次采集使用独立文件，保留场景编号方便人工对照。
curl http://127.0.0.1:6060/debug/pprof/goroutineleak > run-01.prof
curl http://127.0.0.1:6060/debug/pprof/goroutineleak > run-02.prof

# 进入交互界面后，按函数名查看累计阻塞位置。
go tool pprof run-02.prof
# 在 pprof 提示符中输入：top
# 再输入：list processBatch

修复退出路径，再重复采集

对上面的例子，最小修复可以让结果发送不依赖调用方继续接收，例如按任务数给 channel 设置容量；更完整的工程修复则是把取消信号、发送失败和 worker 回收设计成同一条生命周期。容量方案只适合结果数量有明确上限的场景，不能掩盖无限制生产者。

func processBatch(items []int) ([]int, error) {
    // 容量覆盖所有任务，调用方提前返回时 worker 仍能完成一次发送。
    resultsCh := make(chan result, len(items))
    for _, item := range items {
        go func(item int) {
            value, err := process(item)
            resultsCh 

修复后用完全相同的请求场景再采集至少两轮。理想结果不是 profile 变成零，而是泄漏节点不再随请求轮次增长；如果业务本来就存在长期 worker，应把它们的正常生命周期记录在基线说明中，而不是强行消除。

把基线变成可执行的排查习惯

可以把采集动作放在压测或回归流程的尾部：先执行固定流量，再采集 goroutineleak，最后比较重点函数的数量和堆栈。线上采集应控制频率，因为泄漏检测会增加垃圾回收阶段的工作；官方说明也建议结合测试工具和不同层级的 profile 一起使用。

常见问题

goroutineleak profile 能发现所有泄漏吗？

不能。它主要识别阻塞在 Go channel 和部分 sync 原语上的 goroutine；网络 I/O、文件 I/O 或自定义同步实现需要其他工具和代码审查配合。

为什么普通 goroutine profile 数量很多，但泄漏 profile 没有增长？

普通 profile 包含暂时阻塞和设计上长期存在的 worker，而泄漏 profile 只筛出满足其可达性与阻塞条件的对象。采集时机和业务流量也会造成差异。

只给 channel 加容量是不是万能修复？

不是。容量只是在结果数量有界时避免发送端因调用方提前返回而卡住；如果生产者数量不受控，仍应使用取消信号、关闭通道或等待组来明确退出契约。