Go runtime.AddCleanup 与 SetFinalizer 有什么区别

维护一段旧 Go 代码时，我最容易误判的一件事，是把 runtime.SetFinalizer 和 Go 1.24 引入的 runtime.AddCleanup 当成同一个 API 的新旧写法。它们都在对象变得不可达后做兜底清理，但绑定对象的方式、回调拿到的参数、循环引用的风险和可取消能力并不一样。

官方资料：https://pkg.go.dev/runtime

新代码通常优先选 AddCleanup；旧代码迁移时要重新检查对象约束和回调是否反向持有对象。无论选哪一个，都不要把它当成进程退出前必然执行的业务清理机制，文件、连接和事务仍应由显式 Close、Release 或提交逻辑负责。

先把两种机制放回同一张资源关系图

先看 API 的数据形状。AddCleanup(ptr, cleanup, arg) 观察的是 ptr，回调收到的是独立的 arg；典型场景是 Go 对象包着文件描述符，清理函数只拿描述符去释放外部资源。一个对象还可以挂多个 cleanup，甚至可以把 cleanup 绑定到同一块分配中的内部指针。

SetFinalizer(obj, finalizer) 则把 finalizer 直接挂到对象上，回调参数就是该对象。运行时发现对象不可达后会清除关联并在独立 goroutine 中调用 finalizer；对象在这次调用中重新变得可达，之后还要再次不可达才可能被释放。

这就是两者最值得记住的差异：AddCleanup 可以让回调只捕获资源句柄，避免回调参数本身把对象重新连回来；SetFinalizer 天然把对象交给回调，设计不慎就会延长对象图的生命周期。

真正影响选择的是对象约束与清理时机

这里有一个常见坑：Cleanup.Stop 不是“保证清理函数永远不执行”的全局开关。如果指针已经不可达，cleanup 已经入队，Stop 不再生效；想保证取消成功，必须让传给 AddCleanup 的指针在调用 Stop 期间仍然可达。

两种回调都要注意 KeepAlive。如果对象最后一次被编译器认为使用的位置早于底层系统调用，GC 可能提前让它不可达；把对象传给 runtime.KeepAlive，可以把“至少活到这里”写清楚。这个判断解决的是过早回收，不是让回调变成同步释放。

迁移时按资源生命周期做决定

如果是在 Go 1.24 以上写新的包装类型，我会把“显式释放”放在主路径，再用 AddCleanup 做兜底。例如回调只接收资源标识，不把包装对象塞进参数：

type Handle struct {
	resourceID int64
}

func attachCleanup(h *Handle, id int64) runtime.Cleanup {
	return runtime.AddCleanup(h, func(resourceID int64) {
		// 兜底释放外部资源；业务成功路径仍应主动调用 Release。
		releaseExternalResource(resourceID)
	}, id)
}

func useHandle(h *Handle) {
	// 这里执行确定的业务操作和显式释放，不等待 GC。
	defer releaseExternalResource(h.resourceID)
	// 使用 h.resourceID 完成一次受控操作。
	runtime.KeepAlive(h)
}

这段示例表达的是结构，不代表应该把释放函数复制到生产项目：如果 Release 会被显式路径和 cleanup 同时调用，就要让释放动作具备幂等性，或在显式释放后及时调用句柄的 Stop。相反，只有在维护旧版本兼容代码、确实需要对象本身参与清理时，才继续保留 SetFinalizer，并检查回调是否反向引用对象。

常见问题

AddCleanup 会在程序退出时自动释放文件吗？

不保证。它依赖对象不可达和 GC 调度，进程退出前可能没有机会运行；文件和连接必须显式关闭。

有了 AddCleanup 还需要 KeepAlive 吗？

需要时仍要用。只要底层调用要求对象保持可达，就在最后一次实际使用之后调用 KeepAlive，避免清理过早入队。

SetFinalizer 能不能直接替换成 AddCleanup？

不能只做名称替换。应先把对象回调改成独立资源参数，检查循环引用、Stop 时机和重复释放，再逐个迁移。

判断标准可以压缩成一句话：业务代码负责确定性释放，AddCleanup 负责更轻量的 GC 兜底；SetFinalizer 只在旧约束确实需要对象回调且完成生命周期审查时继续使用。