在集成测试中采集 goroutine 泄漏剖析结果

如果集成测试只检查 HTTP 状态码，后台 goroutine 在请求结束后悄悄卡住，通常要到压测或线上才会暴露。Go 1.27 已经把 goroutineleak profile 作为正式能力提供出来，适合在测试走完真实请求路径后留下一个可下载、可复盘的 pprof 工件。

官方资料：https://go.dev/doc/go1.27　https://pkg.go.dev/runtime/pprof　https://pkg.go.dev/net/http/pprof

一、先把测试服务器暴露成可采集的剖析入口

集成测试最稳妥的做法是给被测服务使用一个明确的 mux，把业务路由和 profile 路由放进同一个测试服务器。这样测试请求到达哪个实例、profile 从哪个实例采集都很清楚，也不会因为导入 net/http/pprof 改写进程级默认路由。

func newIntegrationServer(t *testing.T) *httptest.Server {
	// 测试 mux 同时承载业务入口和泄漏 profile，避免依赖全局 DefaultServeMux。
	mux := http.NewServeMux()
	mux.HandleFunc("/api/jobs", handleJobs)
	// Go 1.27 提供 goroutineleak profile，Handler 负责输出 pprof 格式数据。
	mux.Handle("/debug/pprof/goroutineleak", pprof.Handler("goroutineleak"))
	return httptest.NewServer(mux)
}

这里的关键不是把所有 pprof 页面都开放出来，而是只挂载集成测试需要的 profile。net/http/pprof.Handler 会根据名称返回对应处理器；如果项目仍使用 Go 1.26 或更早版本，应先确认工具链版本，否则这个名称并不具备同样的兼容前提。

二、集成测试先触发真实路径，再保存 profile

采集顺序要贴近用户动作：先调用会创建后台任务的业务接口，再等待接口返回，最后抓取 profile。不要在测试开始时就采集，那只能说明测试框架本身的 goroutine 状态，无法对应本次业务请求。

func TestIntegrationLeakProfile(t *testing.T) {
	// 长流程集成测试可通过 -short 跳过，避免普通单元测试被外部服务拖慢。
	if testing.Short() {
		t.Skip("skip integration profile in short mode")
	}
	srv := newIntegrationServer(t)
	defer srv.Close()

	// 先走真实业务入口，让待观察的后台任务有机会进入生命周期。
	resp, err := srv.Client().Post(srv.URL+"/api/jobs", "application/json", strings.NewReader(`{"count":3}`))
	if err != nil {
		t.Fatal(err)
	}
	resp.Body.Close()

	// 从同一个测试实例采集 goroutine 泄漏 profile。
	profileResp, err := srv.Client().Get(srv.URL + "/debug/pprof/goroutineleak")
	if err != nil {
		t.Fatal(err)
	}
	defer profileResp.Body.Close()
	if profileResp.StatusCode != http.StatusOK {
		t.Fatalf("profile status: %s", profileResp.Status)
	}

	// 允许 CI 通过环境变量指定工件路径；未指定时使用测试临时目录。
	out := os.Getenv("GOROUTINE_LEAK_PROFILE")
	if out == "" {
		out = filepath.Join(t.TempDir(), "goroutineleak.pb.gz")
	}
	if err := os.MkdirAll(filepath.Dir(out), 0o755); err != nil {
		t.Fatal(err)
	}
	f, err := os.Create(out)
	if err != nil {
		t.Fatal(err)
	}
	defer f.Close()
	if _, err := io.Copy(f, profileResp.Body); err != nil {
		t.Fatal(err)
	}
	t.Logf("goroutineleak profile saved to %s", out)
}

这段测试只负责生成证据，不把 profile 字节数直接当作通过条件。这样 CI 可以上传固定目录，开发者也能在本地用同一份工件复盘；如果业务接口本身失败，测试仍会在采集前明确失败，不会把“没有请求成功”误认为“没有泄漏”。

三、怎么读结果，区分泄漏证据与正常阻塞

采集到的是 pprof 二进制数据，第一步先看总量和主要调用栈，再回到代码核对阻塞原语的所有权。goroutineleak 关注的是永久无法解除的阻塞，不等于当前进程里所有等待中的 goroutine。

# 指定工件路径运行集成测试，便于 CI 上传固定文件。
GOROUTINE_LEAK_PROFILE=artifacts/goroutineleak.pb.gz \
go test ./internal/integration -run TestIntegrationLeakProfile -count=1 -v

# 先看汇总，再按函数名展开可疑调用栈。
go tool pprof -top artifacts/goroutineleak.pb.gz
go tool pprof artifacts/goroutineleak.pb.gz
# 进入交互模式后，可用 top、list FunctionName 查看热点与源码位置。

如果调用栈停在向无人接收的 channel 发送、从永远不关闭的 channel 接收，或等待一个生命周期已经结束的 sync.Mutex、sync.WaitGroup、sync.Cond，就应沿着该原语的引用关系找退出路径。反过来，短暂等待网络 I/O、文件 I/O，或被仍然可达的全局对象持有的同步原语，不应只凭“出现等待”就判成泄漏。

四、让 CI 只收集证据，不把采样噪声当断言

把这类检查分成两层更稳：第一层每次集成测试都保存 profile，保证问题发生时有材料；第二层再根据团队约定做人工复盘、基线比较或定向断言。单次 profile 可能受请求时序影响，而 Go 官方也明确说明该能力只覆盖一部分并发阻塞场景。

这样安排后，集成测试承担“留下可定位证据”的职责，profile 阅读承担“解释证据”的职责，修复代码再承担“结束后台生命周期”的职责。三者分开，既能减少误报，也能让 CI 工件在偶发并发问题出现时真正有用。

相关问题

goroutineleak 和普通 goroutine profile 有什么区别？

普通 profile 展示当前 goroutine 的栈；goroutineleak 只筛出运行时判断为永久阻塞的一部分 goroutine，适合缩小排查范围，但不是完整的并发诊断替代品。

集成测试一定要启动 HTTP pprof 服务吗？

不一定。若测试和被测服务在同一进程，也可以直接使用 runtime/pprof.Lookup("goroutineleak") 写入文件；HTTP handler 更适合验证真实服务 mux 与部署形态。