Go runtime.AddCleanup 如何避免资源清理陷阱：终结回调、KeepAlive 与关闭顺序

给文件描述符、映射区或外部句柄包一层 Go 对象时，最容易留下的 bug 不是“忘了写回调”，而是把兜底回收当成了确定发生的关闭动作。Go 1.24 的 runtime.AddCleanup 让清理函数可以和对象解绑，但它仍然受可达性和垃圾回收调度影响；生产代码应先保证显式关闭，再把 cleanup 当作漏网保护。

AddCleanup 适合兜底，不适合替代 Close；当底层操作必须完成后对象才能失效时，在最后一次使用之后调用 runtime.KeepAlive。

资源包装对象真正需要两个关闭出口

假设 FileHandle 持有一个操作系统文件描述符。调用方正常路径会执行 Close，但异常返回、提前丢弃对象或某个分支忘记关闭时，仍希望底层描述符最终得到处理。这个需求可以拆成两条路径：显式关闭解决时序，runtime.AddCleanup 只负责兜底。

二者不能互换。cleanup 什么时候排队、什么时候运行都不是业务协议的一部分；如果事务提交、文件落盘或网络发送必须在关闭前完成，就应该把这些动作写进显式方法，而不是等待 GC。

AddCleanup 的三个参数如何对应资源生命周期

官方签名是 runtime.AddCleanup(ptr, cleanup, arg)。ptr 是需要被观察可达性的包装对象，cleanup 接收释放资源所需的参数，arg 是传给回调的值。下面的示例用整数描述符演示边界，实际项目中应把关闭错误写入可观测日志。

package main

import (
    "fmt"
    "runtime"
)

type FileHandle struct {
    fd     int
    closed bool
}

func releaseFD(fd int) {
    fmt.Println("cleanup fd", fd)
}

func NewFileHandle(fd int) *FileHandle {
    h := &FileHandle{fd: fd}
    runtime.AddCleanup(h, releaseFD, fd)
    return h
}

func (h *FileHandle) Close() {
    if h.closed {
        return
    }
    h.closed = true
    releaseFD(h.fd)
}

这里的 fd 只是示例资源。真实实现要让显式 Close 与 cleanup 共享一个可验证的幂等状态，否则正常关闭后，兜底回调仍可能再次释放同一个句柄。只有在对象不可达后，运行时才会把这次 清理回调排入执行队列。

显式 Close 成功后为什么还要处理 Cleanup.Stop

更稳妥的包装器会保存 runtime.Cleanup 返回值。显式关闭完成后调用 Stop，表达“这次资源释放已经由业务路径负责”。如果 cleanup 已经开始，Stop 不会把正在执行的回调强行中断，因此回调本身仍应安全、短小并允许重复到达。

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

func NewManagedHandle(fd int) *FileHandle {
    h := &FileHandle{fd: fd}
    h.cleanup = runtime.AddCleanup(h, releaseFD, fd)
    return h
}

func (h *FileHandle) Close() {
    if h.closed {
        return
    }
    h.closed = true
    h.cleanup.Stop()
    releaseFD(h.fd)
}

并发场景还需要互斥或原子状态保护；上面的代码突出的是顺序，不是一个可以直接替换所有资源类型的线程安全实现。若底层关闭本身可重复调用，也可以把幂等性下沉到资源层。

KeepAlive 要放在最后一次底层调用之后

编译器会根据后续是否还用到变量判断对象何时可以变成不可达。对于通过对象间接持有外部资源的代码，不能只看源码里“逻辑上还在函数内”；如果底层调用只拿到了一个描述符，包装对象可能已经没有新的 Go 级引用。

func (h *FileHandle) ReadAt(buf []byte, offset int64) (int, error) {
    n, err := readFD(h.fd, buf, offset)
    runtime.KeepAlive(h)
    return n, err
}

KeepAlive 的位置很具体：它应紧跟在必须保证对象存活的最后一次操作之后。它不会执行 cleanup，不会阻塞等待 GC，也不会把一个已经显式关闭的资源重新打开。

几个容易误用的边界

• 把 cleanup 当定时器：对象不可达只代表满足了排队条件，不代表回调会在某个固定时间点执行。
• 回调里做业务收尾：订单提交、事务提交、重要日志不能依赖独立 goroutine 的兜底回调。
• 关闭后仍访问包装对象：先定义状态机，避免 Close 与读写并发造成重复释放或使用已关闭句柄。
• 用 KeepAlive 代替生命周期设计：它只覆盖某一个底层操作的存活边界，不能代替所有权转移和显式释放。

最小验证：先测显式路径，再观察兜底路径

测试显式路径时，断言 Close 后资源只释放一次，并确认 Cleanup.Stop 返回后不会再触发同一回调。测试兜底路径时，可以让对象失去引用后调用 runtime.GC()，再通过同步信号等待回调完成；这个测试只能验证最终可观察结果，不能把 GC 的时间当成产品承诺。

如果包装的是文件、socket 或 C 资源，最好再加入进程级资源计数、关闭错误日志和高并发回归。单元测试通过，只能说明示例的状态变化正确，不能证明每种异常退出路径都已经覆盖。

相关问题

AddCleanup 能完全替代 SetFinalizer 吗？

新代码通常应优先考虑 AddCleanup，但这不等于它替代了显式资源管理。是否迁移仍要看对象所有权、资源关闭时序和回调是否可幂等。

调用 Cleanup.Stop 后还需要 Close 吗？

需要。Stop 只停止尚未开始的兜底清理，不负责释放底层资源；正常路径仍应执行显式 Close。

runtime.GC() 能保证 cleanup 立即执行吗？

不能把它当作实时调度接口。测试中可以用 GC 加同步信号促成回调，但业务代码不应依赖固定执行时间。

总结

runtime.AddCleanup 解决的是“对象被遗忘后仍有一道保护”，而不是“什么时候关闭资源”的业务决定。把显式 Close、Cleanup.Stop 和必要位置的 KeepAlive 组合起来，再用幂等状态和可观测信号验证，才能让资源包装器在正常、异常和并发路径下都说得清楚。