Go runtime.AddCleanup 怎么安排清理回调：关联对象、保活与停止边界

给一个包装了文件句柄、连接或临时目录的 Go 对象安排兜底清理时，Go 1.24 的 runtime.AddCleanup 比给对象挂一个单独的终结器更容易拆分职责：对象变得不可达后，运行时会在独立 goroutine 中调用 cleanup(arg)。但它不是定时器，不能代替正常的 Close；真正决定回调能否安全执行的，是对象是否还需要保持可达，以及退出路径是否已经主动停止清理。

AddCleanup 适合做资源释放的最后一道保险：显式关闭负责确定性，KeepAlive 负责延长最后一次使用前的可达性，Cleanup.Stop 负责在显式清理完成后取消尚未运行的兜底回调。

为什么 Go 1.24 要新增 AddCleanup

旧代码常用 runtime.SetFinalizer 给包装对象安排兜底动作。它能工作，却把一个对象和一个终结器绑定得很紧：同一个指针不方便拆出多个独立清理动作，循环引用也容易让资源生命周期变得难以推断。Go 1.24 的官方说明把 AddCleanup 定位成更灵活的清理机制，新代码通常应优先考虑它。

这里的“清理”不是业务状态变更。比如 FileBox 只负责保存文件名和句柄，清理函数接收独立的 fileName 参数；当 FileBox 不再被程序引用时，回调才有机会删除临时文件。这个分离正是它比把对象塞进闭包更重要的地方。

AddCleanup 的回调何时才安全

下面的例子把临时文件路径作为清理参数。正常路径仍然先显式关闭并删除文件，AddCleanup 只作为异常退出或遗漏清理时的兜底：

type FileBox struct {
    file *os.File
}

func openTemp() (*FileBox, runtime.Cleanup, error) {
    file, err := os.CreateTemp("", "go-cleanup-")
    if err != nil {
        return nil, runtime.Cleanup{}, err
    }
    box := &FileBox{file: file}
    cleanup := runtime.AddCleanup(box, func(fileName string) {
        _ = os.Remove(fileName)
    }, file.Name())
    return box, cleanup, nil
}

func useTemp(box *FileBox) error {
    if _, err := box.file.WriteString("payload"); err != nil {
        return err
    }
    runtime.KeepAlive(box)
    return box.file.Close()
}

图中只保留了这段调用链的三个稳定节点：AddCleanup 注册回调，cleanup 在对象不可达后被运行时调用，KeepAlive 把可达性保障放到最后一次使用之后。它不表示回调会紧接着 KeepAlive 执行，垃圾回收没有这样的时间承诺。

清理函数和参数为什么不能带回对象

AddCleanup 的 ptr、cleanup 和 arg 之间不能形成从清理函数或参数回到 ptr 的可达路径。下面这种写法看起来方便，实际上让闭包持有 box，对象就可能一直可达，回调也就没有机会运行：

box := &FileBox{file: file}
runtime.AddCleanup(box, func(*FileBox) {
    _ = box.file.Close() // 闭包反向持有 box，不要这样写
}, box)

把资源句柄、文件名或一个不含包装对象的值作为 arg，通常更容易审计。官方实现还会对最直接的错误做保护：如果 arg 和 ptr 相等，会直接触发 panic，因为这种关系下清理不会发生。

Cleanup.Stop 适合处理哪种退出路径

如果业务已经完成显式清理，就不希望兜底回调再次删除同一个文件。此时保存 runtime.Cleanup 返回值，在成功关闭资源后调用 Cleanup.Stop：

box, cleanup, err := openTemp()
if err != nil {
    return err
}

if err := useTemp(box); err != nil {
    return err // 仍保留 cleanup 作为兜底
}
if err := os.Remove(box.file.Name()); err != nil {
    return err
}
cleanup.Stop()

这条路径表达的是“显式删除成功后，撤销尚未发生的 cleanup”。Cleanup.Stop 不是等待已经开始的清理函数结束的同步屏障，因此清理函数本身仍要能承受重复调用、文件已不存在等结果。把 Stop 放在资源释放之前，会留下兜底回调拿到半完成状态的风险。

和 SetFinalizer 怎么选

SetFinalizer 并没有因为新 API 出现就自动失效；需要兼容旧版本或维护旧代码时，仍应先理解原有终结器语义。新代码若要给一个对象拆分多个清理动作，或者要清理对象内部的不同指针，AddCleanup 通常更清楚。

上线前先做四个边界检查

1. 清理回调只接收释放资源所需的值，不把包装对象、其字段指针或会回到包装对象的闭包放进 arg。
2. 关键资源仍由显式 Close 或 Release 管理，不能用 GC 的不确定时机承诺业务完成。
3. 最后一次访问包装对象之后再调用 KeepAlive，尤其是访问底层文件句柄或 cgo 资源的函数。
4. 显式清理成功后才调用 Cleanup.Stop，并让 cleanup 对“资源已经不存在”保持安全。

相关问题

AddCleanup 会在对象离开函数时立刻执行吗？

不会。对象不可达只是回调可以被安排的条件，具体执行时间由垃圾回收和运行时调度决定，不能用它做定时任务。

KeepAlive 应该放在文件关闭之前还是之后？

它应放在最后一次需要对象保持可达的操作之后。示例里写入完成后调用 KeepAlive，随后才关闭文件；重点是覆盖最后一次使用点，而不是机械地放在函数末尾。

Cleanup.Stop 能保证 cleanup 没有并发运行吗？

不能把它理解成并发同步工具。它用于停止尚未运行的清理动作，清理函数仍应具备幂等性或能安全处理资源已被显式释放的情况。

小结

runtime.AddCleanup 解决的是“对象被遗忘时还有一层兜底”，不是把资源管理交给 GC。把清理参数与包装对象分开，用 KeepAlive 标出最后使用点，再在显式释放成功后调用 Cleanup.Stop，这三个动作组合起来，生命周期才比较容易复查。