Go 1.25 runtime.AddCleanup 怎么替代终结器：资源回收时机与调试边界

升级到 Go 1.25 后，团队常会顺手把旧的 runtime.SetFinalizer 换成 runtime.AddCleanup。这个替换不是把函数名改掉就结束：清理回调拿不到原对象，执行时间仍由 GC 决定，文件、连接这类资源也仍然应该由显式的 Close 管理。

Go 1.25 这次改进解决了什么

runtime.AddCleanup(ptr, cleanup, arg) 会在 ptr 不再可达后排队调用 cleanup(arg)。它与终结器最关键的差别是：回调不接收那个已经不可达的对象本身，因此不会因为回调参数再次持有对象而制造复活路径。

Go 1.25 的运行时还允许清理函数并发、并行执行，这让它更适合做轻量的兜底动作。不过，清理队列依旧不是确定时钟；程序退出、GC 时机和回调排队都不能作为业务协议的一部分。

最小写法：让 cleanup 只拿到外部资源句柄

下面的例子把清理参数设计成一个整数句柄。真实项目里，回调可以关闭一个不便于直接暴露给业务层的底层资源，但主流程仍要提供明确的关闭方法。

type Buffer struct {
	fd int
}

func newBuffer(fd int) *Buffer {
	b := &Buffer{fd: fd}
	runtime.AddCleanup(b, func(fd int) {
		_ = closeFD(fd) // 只做兜底清理，不承载业务逻辑
	}, fd)
	return b
}

func (b *Buffer) Close() error {
	if b.fd 

核对点有两个：第一，cleanup 的参数是 fd，不是 b；第二，Close 仍然由调用方掌握确定时机。为了避免显式关闭后又被兜底回调重复处理，生产代码还需要用一次性状态或句柄所有权规则保证幂等。

从 SetFinalizer 迁移时，哪些语义不能照搬

SetFinalizer 的回调通常拿到对象指针，开发者很容易在回调中访问对象字段。迁移到 AddCleanup 后，应把必要的、足够小的清理数据在注册时单独提取出来；不要在闭包里捕获 b，也不要把 b 作为第三个参数。

// 错误方向：cleanup 参数或闭包重新持有 b
runtime.AddCleanup(b, func(*Buffer) { /* ... */ }, b)

// 正确方向：只传递独立值或独立资源对象
fd := b.fd
runtime.AddCleanup(b, func(fd int) { _ = closeFD(fd) }, fd)

如果清理参数正好是传给 AddCleanup 的同一个指针，运行时会把它视为明显的错误用法；如果闭包间接捕获被观察对象，也会让“对象不再可达”这个前提失效。

上线前的检查与回滚边界

先保留显式资源释放

数据库事务、临时文件、锁、网络连接和外部服务租约，都应在正常控制流中完成关闭、提交或撤销。cleanup 适合处理遗漏路径、异常返回或包装层无法完全控制的底层资源，不适合替代这些动作。

用运行时诊断观察队列

在测试环境或短时压测中，可以使用 GODEBUG=checkfinalizers=1 观察终结器与清理队列的异常迹象。重点看清理是否因闭包引用、循环引用或长时间阻塞而堆积；不要把一次 GC 后“暂时没看到回调”直接判定为失败。

给迁移保留可回退开关

如果旧实现依赖了对象字段，先把清理数据拆成独立结构，再替换注册方式。回归测试要覆盖显式关闭、重复关闭、对象提前释放和进程正常退出四条路径；发现资源数量持续上涨时，优先修复所有权，而不是强行提高 GC 频率。

相关问题

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

不会。它依赖对象变得不可达以及后续 GC 调度，执行时间不适合做实时资源协议。

AddCleanup 能完全替代 Close 吗？

不能。可观察、可预测的资源释放仍应由显式方法完成，cleanup 只适合作为兜底。

清理回调里能做很慢的网络操作吗？

不建议。长时间阻塞会拖慢清理队列；需要复杂动作时，应把信号交给独立的、可控生命周期的工作协程。

最后的判断

这次迁移的重点不是把终结器换成一个更新的 API，而是重新划清资源所有权：业务路径负责确定性释放，运行时 cleanup 负责最后一道保险。只要清理参数独立、回调短小，并用诊断开关和资源计数做回归，Go 1.25 的新语义才会真正降低风险。