Go 测试清理逻辑迁移：从 defer 到 t.Cleanup 的正确写法

Go 单元测试写久了，测试 helper 会越来越多：创建临时文件、启动本地 HTTP 服务、准备测试库、改环境变量，再把资源交给测试函数使用。最容易出问题的地方，是 helper 内部顺手写了 defer 清理资源，结果 helper 一返回资源就被释放，真正的测试还没开始使用。

testing.T.Cleanup 更适合这类测试资源管理。它把清理函数挂到当前测试或子测试的生命周期上：测试通过、失败、调用 t.Fatal 提前停止，清理动作都会在当前测试结束时运行。这样 helper 可以继续负责创建资源，但资源释放时机由 testing.T 统一管理。

哪些测试清理逻辑适合迁移

不是所有 defer 都要换成 t.Cleanup。如果资源在当前测试函数里创建，也在当前测试函数里使用，defer 简单直接。例如打开一个文件、立刻读取、函数结束关闭，这种写法没有问题。

真正值得迁移的，是资源创建被封装进 helper，而资源要留给测试函数继续使用的场景：

• helper 创建临时目录、临时文件或 SQLite 测试库。
• helper 启动 httptest.Server，返回服务地址给多个断言使用。
• helper 修改环境变量、全局配置、默认 logger 或 mock 状态。
• helper 给子测试准备不同资源，希望每个子测试结束后独立清理。

这类资源的生命周期应该跟着测试走，而不是跟着 helper 函数走。helper 的职责是准备资源和登记清理动作；什么时候清理，交给 testing.T 更稳。

变更对比：defer 管函数，t.Cleanup 管测试

迁移前先把差异说清楚。defer 的运行时机是“当前函数返回前”，t.Cleanup 的运行时机是“当前测试结束时”。这两个范围不一样，正是很多测试 helper 出错的根源。

旧代码风险：helper 里的 defer 会太早运行

看一个很常见的写法。helper 创建临时文件，把路径返回给测试函数。为了不泄漏文件，作者在 helper 内部加了 defer os.Remove：

package report_test

import (
    "os"
    "testing"
)

func newTempReportFile() string {
    f, err := os.CreateTemp("", "report-*.txt")
    if err != nil {
        panic(err)
    }
    name := f.Name()
    _ = f.Close()

    defer os.Remove(name)
    return name
}

func TestWriteReport(t *testing.T) {
    path := newTempReportFile()

    if err := os.WriteFile(path, []byte("ok"), 0644); err != nil {
        t.Fatalf("write report: %v", err)
    }
}

这段代码的问题在于：newTempReportFile 返回之前就会运行 defer os.Remove(name)，临时文件已经被删除。测试函数拿到的是一个刚被清理掉的路径，后面再写入就可能失败。

如果 helper 创建的是测试服务，风险也类似：helper 返回地址前就关闭服务，测试函数拿到的地址无法访问。文件、连接、服务、环境变量恢复，本质上都是同一类生命周期问题。

新写法：让 helper 接收 testing.T

迁移后的写法，是让 helper 接收 *testing.T，并把清理动作登记到当前测试上。helper 仍然和资源创建放在一起，但释放时机延后到测试结束。

package report_test

import (
    "os"
    "testing"
)

func newTempReportFile(t *testing.T) string {
    t.Helper()

    f, err := os.CreateTemp("", "report-*.txt")
    if err != nil {
        t.Fatalf("create temp report file: %v", err)
    }
    name := f.Name()

    if err := f.Close(); err != nil {
        t.Fatalf("close temp report file: %v", err)
    }

    t.Cleanup(func() {
        _ = os.Remove(name)
    })

    return name
}

func TestWriteReport(t *testing.T) {
    path := newTempReportFile(t)

    if err := os.WriteFile(path, []byte("ok"), 0644); err != nil {
        t.Fatalf("write report: %v", err)
    }
}

t.Helper() 也很重要。它告诉测试框架：这个函数是辅助函数。helper 内部调用 t.Fatalf 时，失败行号会更倾向于指向调用 helper 的测试代码，排查起来更直观。

如果资源是目录，优先考虑标准库已经提供的 t.TempDir()。它内部会自动登记清理动作，代码更短：

func TestRenderReport(t *testing.T) {
    dir := t.TempDir()
    path := dir + "/report.txt"

    if err := os.WriteFile(path, []byte("ok"), 0644); err != nil {
        t.Fatalf("write report: %v", err)
    }
}

回归检查：失败、子测试和并发测试都要覆盖

迁移清理逻辑最怕“正常路径没问题，失败路径残留资源”。改完 helper 后，至少要看三类场景。

失败路径仍然清理

测试中途调用 t.Fatal，或者断言失败提前停止时，已经登记的 t.Cleanup 仍会运行。这正是它比 helper 内部 defer 更适合测试资源的原因。

子测试资源互不影响

在 t.Run 内创建资源时，清理动作跟着当前子测试结束。不同子测试之间不会共享同一份临时目录或测试状态。

func TestReportCases(t *testing.T) {
    cases := []string{"daily", "weekly"}

    for _, name := range cases {
        name := name
        t.Run(name, func(t *testing.T) {
            path := newTempReportFile(t)
            if err := os.WriteFile(path, []byte(name), 0644); err != nil {
                t.Fatalf("write report: %v", err)
            }
        })
    }
}

并发测试不要共享可变资源

如果子测试调用 t.Parallel()，更要避免多个测试共用一个可变目录、全局变量或测试服务。每个子测试单独创建资源并登记清理，失败时更容易定位。

迁移清单：从一类 helper 开始替换

项目里测试 helper 往往很多，不建议一次性全改。更稳的做法是先挑一类资源，例如临时文件或测试服务，迁移后跑完整测试，再推广到其他 helper。

1. 搜索测试代码里的资源 helper，重点看返回路径、连接、服务地址、环境变量恢复的函数。
2. 确认 helper 内部是否用 defer 清理了返回给外部使用的资源。
3. 把 helper 签名改成接收 *testing.T，函数开头调用 t.Helper()。
4. 把清理动作移动到 t.Cleanup(func() { ... }) 里。
5. 目录类资源优先改成 t.TempDir()，环境变量优先使用 t.Setenv()。
6. 补充失败路径和子测试场景，确认清理动作不会太早，也不会残留。
7. 跑 go test ./...，再单独跑有改动的包，观察临时资源和日志输出。

相关问题

defer 在 Go 测试里还能不能用？

可以。资源在同一个测试函数里创建和使用时，defer 仍然简单清楚。资源由 helper 创建并返回给测试函数继续使用时，再优先考虑 t.Cleanup。

t.Cleanup 和 t.TempDir 有什么关系？

t.TempDir() 是更高层的便捷方法，适合目录资源；t.Cleanup 更通用，可以清理文件、关闭服务、恢复全局变量或撤销 mock。

t.Cleanup 的清理顺序需要关心吗？

需要。多个清理函数通常按后注册先运行的顺序收尾。依赖关系复杂时，建议把相关资源的创建和清理封装在同一个 helper 里，避免顺序散落。

子测试里注册的清理函数什么时候运行？

在当前子测试结束时运行。这样每个 t.Run 都能拥有自己的临时目录、测试服务或 mock 状态，减少互相影响。

总结

Go 测试清理逻辑迁移的核心，不是把所有 defer 都替换掉，而是把资源生命周期放回正确的位置。函数内部短资源继续用 defer；helper 创建并返回的测试资源，交给 t.Cleanup 跟随当前测试收尾。这样测试失败、子测试隔离和 helper 复用都会更稳。