Go 1.24 runtime.AddCleanup 怎么替代 SetFinalizer：Stop、KeepAlive 与迁移边界

之前我维护的一个本地缓存文件读取Go服务，高峰期偶尔碰到文件描述符回收变慢的问题。旧代码把 runtime.SetFinalizer 当成最后一道保险，但它既没法保证运行时机，也很容易因为对象间的引用关系把整个回收链搞得特别复杂。Go 1.24 给出了更适配新代码的 runtime.AddCleanup，不过它仍然不是显式 Close 的替代品。

runtime.AddCleanup 提供了比老版 SetFinalizer 边界更清晰的资源兜底能力，只要守好显式释放优先、兜底只做容错、KeepAlive 卡准底层调用边界这几个规则，从旧方案迁移过来基本不会踩之前那些隐性的引用坑。

Go 1.24 到底改了什么

Go 1.24 在运行时包里新增了 runtime.AddCleanup 和 runtime.Cleanup。调用方把对象指针、清理函数和清理参数传给运行时，等对象不再被任何地方引用之后，运行时会在稍后的独立 goroutine 里执行你传入的清理函数。它和旧的 SetFinalizer 都属于“最后兜底”的机制，但设计边界要清晰很多。

这里最容易被误读的点是“更灵活”不等于“更及时”。只要代码需要在函数返回前关闭文件、归还连接或者释放锁，就必须继续用显式的释放方法处理。

为什么 AddCleanup 不该替代显式 Close

把资源包装成结构体之后，推荐的责任分工非常清晰：调用方通过 Close 完成确定性释放，AddCleanup 只做兜底。下面这个小包装器可以把清理动作集中成不会重复执行的函数。

package main

import (
    "fmt"
    "runtime"
)

type Handle struct {
    fd     int
    closed bool
}

func release(h *Handle) {
    if h == nil || h.closed {
        return
    }
    h.closed = true
    fmt.Println("release fd", h.fd)
}

func NewHandle(fd int) *Handle {
    h := &Handle{fd: fd}
    runtime.AddCleanup(h, release, h)
    return h
}

func (h *Handle) Close() {
    release(h)
}

生产环境的代码里，release 还应当处理系统调用错误、并发保护和资源状态校验。示例只保留核心判断逻辑：显式 Close 先把状态标记为已关闭，之后就算清理函数被调度到，也不会重复释放资源。

显式关闭成功后，为什么还要 Stop

如果清理函数已经捕获了外部资源，主动关闭成功之后可以停掉还没执行的兜底动作。只要把 runtime.AddCleanup 的返回值提前保存下来就可以做到：

type Handle struct {
    fd      int
    closed  bool
    cleanup runtime.Cleanup
}

func NewHandle(fd int) *Handle {
    h := &Handle{fd: fd}
    h.cleanup = runtime.AddCleanup(h, release, h)
    return h
}

func (h *Handle) Close() {
    release(h)
    h.cleanup.Stop()
}

Stop 只表示“不要再运行这个清理回调”，并不等于关闭了底层文件或者连接。执行顺序上先完成显式释放，再停止兜底句柄，代码逻辑也更容易复盘审查。

SetFinalizer 迁移时，三个旧习惯要改掉

从旧代码迁移的时候，不要只做函数名直接替换。下面三个边界条件直接决定了迁移之后代码能不能稳定运行。

第一，清理函数不要承担业务结果

清理函数可能很晚才跑，也可能进程退出之前根本没机会执行。它可以释放没人用的native句柄、临时内存映射或者缓存关联数据，但绝对不适合写订单状态、提交事务、发送必须送达的消息这类强要求逻辑。

第二，清理参数不要反向保活目标对象

如果直接把目标对象本身当成清理参数，运行时虽然会判断这类参数不能让目标继续保持可达，但实际写代码的时候更稳妥的方案是传一个独立的轻量资源句柄或者编号。别在清理参数里再存一条指向目标对象的强引用链。

第三，最后一次底层调用后再 KeepAlive

当Go对象只是一个底层句柄的外壳时，编译器可能在最后一次显式使用之后就判定它不再需要存活。如果后面的系统调用还依赖这个对象对应的资源，可以把 runtime.KeepAlive(h) 放在最后一次调用的后面：

func (h *Handle) ReadInto(buf []byte) error {
    err := readNative(h.fd, buf)
    runtime.KeepAlive(h)
    return err
}

KeepAlive 不是能把对象整个函数生命周期都锁死的万能补丁，它只是把对象的存活边界推到了写它的那一行。位置放早了没有任何意义，漏掉最后一次底层调用也会让保护逻辑完全失效。

最小验证：观察 Stop 与回收边界

这类代码不要用“调用一次GC就一定打印某行日志”作为测试断言。GC和清理回调都有调度不确定性，测试只需要验证确定性部分就行，回收观察可以留给带超时容错的辅助检查逻辑。

func TestCloseStopsCleanup(t *testing.T) {
    h := NewHandle(17)
    h.Close()

    if !h.closed {
        t.Fatal("handle was not closed")
    }
    // 不断言清理回调何时运行；只验证 Close 的状态和幂等性。
    h.Close()
}

迁移验收可以按下面的顺序走：

1. 先排查所有 SetFinalizer 调用，标出真正需要兜底的资源场景。
2. 给资源包装器补全幂等的 Close 逻辑，保证重复调用不会重复释放。
3. 用 AddCleanup 注册轻量兜底逻辑，提前保存好返回的 Cleanup 句柄。
4. 显式关闭成功后调用 Stop，底层调用结束之后补上 KeepAlive。
5. 在压力测试里观察资源计数，但不要把某次GC的执行时间当成接口SLA的判断标准。

常见问题：哪些场景不适合依赖清理回调

AddCleanup 会在对象离开作用域后立即运行吗？

不会。对象不可达只是满足了运行的前置条件，实际调用时间完全由运行时调度决定。需要马上释放的资源还是要显式关闭。

Close 之后还需要保留 AddCleanup 吗？

通常值得保留作为异常路径的保险，但清理函数必须是幂等的；显式关闭成功之后可以调用 Cleanup.Stop 取消还没执行的回调。

可以在清理函数里调用复杂的业务代码吗？

不建议。清理函数运行在独立goroutine，执行时机和顺序都没法保证，不适合承担提交、通知或者必须成功的业务动作。

Go 1.23 项目能直接使用 AddCleanup 吗？

不能把它当成旧版本兼容API来用。需要把模块和构建环境升级到包含该API的Go版本，或者暂时自己兼容实现对应的逻辑；迁移之前先确认CI、开发机和生产镜像的编译器版本完全一致。

迁移结论

runtime.AddCleanup 的价值在于把“对象不可达后的兜底动作”表达得更直接，消减掉 SetFinalizer 原来的各种奇怪约束和误用场景。真正可靠的资源管理依旧是显式 Close、幂等状态校验、必要时的 Stop，以及底层调用之后的 KeepAlive。把这四件事分开处理，升级Go 1.24的时候才不会把垃圾回收机制误当成业务生命周期管理器。