Go testing.T.Cleanup 清理回调 panic 时怎么处理

遇到 testing.T.Cleanup 回调 panic，先不要把所有红色日志当成同一个故障。Go 会在测试及其子测试完成后执行 Cleanup，并按“后注册、先调用”倒序处理；清理函数自己 panic 时，测试仍会失败，但测试框架会尽量继续执行剩余清理。若测试主体已经 panic，清理阶段的 panic 通常会被记录为附加信息，原始 panic 仍是主要失败线索。

官方资料：https://pkg.go.dev/testing

先搞清 T.Cleanup 到底什么时候执行

t.Cleanup(fn) 不是注册后立即运行的 defer，它绑定的是当前测试或子测试的生命周期。当前测试函数返回、调用 FailNow 或出现 panic 后，testing 才进入清理阶段；如果有子测试，父测试的 Cleanup 要等子测试完成。

回调顺序是后进先出。下面的写法中，第二个回调先执行，所以依赖关系应当按“先注册底层资源、后注册上层资源”来排：

func TestResource(t *testing.T) {
	// 先登记底层连接，后登记依赖连接的会话。
	t.Cleanup(func() {
		// 这里应先关闭会话，避免底层连接已经消失。
		t.Log("close session")
	})
	t.Cleanup(func() {
		// 后注册的回调会先执行，这里只是顺序示意。
		t.Log("close connection")
	})
}

注意这个例子只说明顺序，不代表日志就是资源关闭的真实结果。工程代码里更重要的是：每个 Cleanup 应该只负责自己拥有的资源，并且重复调用不会破坏状态。

cleanup panic 为什么会让日志看起来像两次失败

testing 包的内部清理逻辑有两种场景。测试主体正常返回时，清理回调的 panic 会直接让该测试失败；测试主体已经 panic 时，框架会回收清理阶段的 panic，记录类似“cleanup panicked with ...”的信息，然后继续保留原始 panic。源码还专门安排了剩余清理回调的处理，因此不能假设第一个 panic 就等于所有资源都未清理。

可以用一个很小的失败输出来理解边界：

--- FAIL: TestCheckout (0.00s)
    cleanup panicked with close: already closed
panic: request failed

上面的两条信息分别指向清理阶段和测试主体。排查时先看最初的业务 panic，再检查 Cleanup 是否重复关闭、使用了已经失效的指针，或在清理过程中调用了不该调用的测试控制方法。

把清理失败变成可定位的测试错误

关闭文件、事务或临时服务时，错误本身通常比 panic 更适合作为测试失败信息。这样既能让测试红起来，也能把资源名称和底层错误保留下来：

func registerCloser(t *testing.T, name string, closeFn func() error) {
	t.Helper()
	t.Cleanup(func() {
		// 清理失败要带资源名，但不要用 panic 覆盖测试主体错误。
		if err := closeFn(); err != nil {
			t.Errorf("cleanup %s: %v", name, err)
		}
	})
}

如果第三方库只能通过 panic 报错，可以把 recover 限制在这个回调内部，并转成测试错误。不要在一个公共 Cleanup 外层包住所有资源，否则会丢失是哪一个资源出错：

func registerUnsafeCleanup(t *testing.T, fn func()) {
	t.Helper()
	t.Cleanup(func() {
		// 只隔离不可控的第三方回调，当前测试 goroutine 内才可捕获。
		defer func() {
			if value := recover(); value != nil {
				t.Errorf("cleanup panic: %v", value)
			}
		}()
		fn()
	})
}

这不是把 panic 隐藏掉，而是把它变成带上下文的测试失败。若 panic 发生在另一个 goroutine，必须在线程启动处自行 recover 并通过 channel 或错误收集器回传；外层的 t.Cleanup 无法跨 goroutine 接住它。

用检查清单收住顺序、并发和重复清理

复查时只运行目标测试并打开详细日志：

# 只筛选目标测试，观察 Cleanup 的失败上下文。
go test -run '^TestResource$' -count=1 -v

如果需要确认回调顺序，可以在回调中写短日志；不要用固定时间等待“等它清理完”。Cleanup 只负责测试生命周期内的同步收尾，后台 goroutine 的退出仍应通过 context、WaitGroup 或明确的停止协议完成。

常见问题

Cleanup 里 panic 会被自动忽略吗？

不会。它会让测试失败；在测试主体已经 panic 的场景，testing 可能把 cleanup panic 作为附加日志记录，但这不等于错误消失。

能不能在 Cleanup 里调用 t.Fatal？

不建议把 Fatal 当作清理错误处理手段。清理阶段应优先用 t.Errorf 报告，并确保后续资源仍有机会释放。

为什么 recover 没接住 Cleanup 的 panic？

recover 只能捕获同一个 goroutine、同一条 panic 栈上的 panic。异步 goroutine 必须在其自身入口处理错误。

Cleanup 和 defer 应该怎么选？

测试资源通常用 t.Cleanup，因为它覆盖测试失败、子测试和 FailNow 等生命周期；局部函数内的临时逻辑仍可用 defer。不要重复登记同一个资源的所有权。