Go runtime.AddCleanup 的清理函数为什么不能依赖对象本身

Go 的 runtime.AddCleanup 允许把一个清理函数挂到对象上，但清理函数不能通过闭包或参数重新持有这个对象本身。最容易踩坑的写法是：把 ptr 放进 cleanup 闭包，或者把包含 ptr 的结构作为 arg 传进去。这样垃圾回收器仍能从清理关系反向找到目标对象，清理就没有变成可回收对象的“后续动作”。

正确思路是把三者拆开：ptr 只表示“观察哪个对象是否仍可达”，cleanup 只接收清理动作需要的数据，arg 只携带不会回指 ptr 的资源句柄、路径或值类型参数。

本文只解释 AddCleanup 的 cleanup 参数、对象捕获与参数化清理函数之间的生命周期边界，不展开 SetFinalizer 的完整迁移方案。

官方文档：https://pkg.go.dev/runtime#AddCleanup

先看 AddCleanup 的三个角色

AddCleanup 的签名可以简化理解为 AddCleanup(ptr, cleanup, arg)。当 ptr 不再可达后，运行时会在某个稍后的时间调用 cleanup(arg)，并且调用发生在独立 goroutine 中。这里的“稍后”不是确定的延迟，也不是函数返回时立即执行。

典型模型是“对象包装底层资源”：对象是 ptr，文件描述符或临时文件路径是 arg，cleanup 根据这个独立参数释放资源。底层资源可以被清理函数使用，但清理参数不能反向持有包装对象。

为什么闭包捕获 ptr 会让清理失效

下面的写法看起来直观，却建立了从 cleanup 闭包回到 ptr 的引用：

package main

import "runtime"

type Resource struct {
	fd int
}

func registerBad(r *Resource) {
	// cleanup 闭包捕获 r，清理关系可能反向持有目标对象。
	runtime.AddCleanup(r, func(_ int) {
		_ = r.fd // 这里使用了 r，形成从 cleanup 到 ptr 的回指
	}, r.fd)
}

问题不在于闭包语法本身，而在于可达性。运行时必须先让 ptr 变成不可达，才有机会把 cleanup 放入待执行队列；如果 cleanup 本身还能找到 ptr，回收条件就被破坏。官方文档也明确说明：只要 ptr 能从 cleanup 或 arg 到达，目标对象就不会被收集，清理也不会运行。

把对象藏进 arg 同样不安全：

type cleanupArg struct {
	owner *Resource // 仍然保存目标对象，不能作为 AddCleanup 的 arg
	fd    int
}

func registerAlsoBad(r *Resource) {
	arg := cleanupArg{owner: r, fd: r.fd}
	// arg.owner 让清理参数反向指回 r，问题没有因为换了参数名而消失。
	runtime.AddCleanup(r, func(a cleanupArg) {
		_ = a.fd
	}, arg)
}

把清理函数改成参数化形式

修复时不要在 cleanup 中“找回对象”，而是提前提取清理所需的数据。下面用文件描述符演示：清理函数只拿到一个整数，不需要读取 Resource 的其他字段。

package main

import (
	"fmt"
	"runtime"
)

type Resource struct {
	fd int
}

func releaseFD(fd int) {
	// 清理函数只接收独立资源句柄，不访问拥有该句柄的 Resource。
	fmt.Printf("release fd=%d\n", fd)
}

func registerGood(r *Resource) runtime.Cleanup {
	fd := r.fd
	// arg 是值类型，cleanup 不通过闭包捕获 r，因此不会回指 ptr。
	return runtime.AddCleanup(r, releaseFD, fd)
}

实际项目中，arg 可以是文件描述符、资源 ID、路径字符串或专门设计的无回指参数结构。判断标准不是“它是不是指针”，而是“从 cleanup 和 arg 出发，能不能沿着字段、接口、闭包环境找到 ptr”。即使参数是接口类型，也要检查其动态值是否包含目标对象。

如果资源释放需要多个字段，可以只复制这些字段：

type releaseArg struct {
	fd   int
	name string
}

func releaseResource(a releaseArg) {
	// 只使用复制后的资源信息；不要把 Resource 指针塞回参数结构。
	fmt.Printf("release %s on fd=%d\n", a.name, a.fd)
}

func registerWithValueArg(r *Resource, name string) runtime.Cleanup {
	arg := releaseArg{fd: r.fd, name: name}
	// arg 内部没有 r，cleanup 也没有捕获 r。
	return runtime.AddCleanup(r, releaseResource, arg)
}

把清理当作异步兜底，而不是确定性 defer

AddCleanup 的定位是对象不可达后的兜底清理，不适合替代“用完立刻释放”的确定性资源管理。清理可能与用户创建的 goroutine 并发运行，也可能与其他 cleanup 并发运行；多个清理之间没有规定执行顺序。进程退出前也不保证 cleanup 一定执行。

因此，文件、连接和锁等资源仍应优先使用显式的 Close、Unlock 或作用域内的 defer。AddCleanup 更适合做遗漏路径的兜底，并且 cleanup 本身要能承受并发调用环境，不能依赖另一个 cleanup 已经先完成。

如果业务在资源仍然使用时就让对象不可达，可以用 runtime.KeepAlive 把对象的可达性延长到最后一次使用之后：

func useResource(r *Resource) {
	// 先使用 r 代表的底层资源。
	useFD(r.fd)

	// 确保清理不会早于这次资源使用发生。
	runtime.KeepAlive(r)
}

KeepAlive 解决的是“对象过早变成不可达”的问题，不是让 cleanup 可以安全捕获对象。清理函数和参数仍然必须保持不回指 ptr 的设计。

Stop、并发和边界条件怎么安排

AddCleanup 返回的 runtime.Cleanup 可以调用 Stop 取消清理，但只有在清理尚未排队时才有效。要保证 Stop 真正移除清理关系，调用者必须保证传给 AddCleanup 的指针在调用 Stop 期间仍然可达。

func closeExplicitly(r *Resource, cleanup runtime.Cleanup) {
	// 这里仍持有 r，保证 Stop 调用期间目标指针可达。
	cleanup.Stop()
	// 之后由显式关闭路径负责资源释放，避免兜底清理重复执行。
	closeFD(r.fd)
}

还要留意三个边界：零大小对象的 cleanup 不保证执行；包级变量初始化期间创建的对象可能由链接器分配，也不保证执行；cleanup 运行时机不确定，所以不能把它当成事务提交、日志落盘或进程退出钩子。

一张清单判断写法是否安全

1. 先标出 ptr：它只是被观察生命周期的目标，不是 cleanup 的工作对象。
2. 检查 cleanup 的闭包环境：是否直接捕获了 ptr、拥有者、包含它的结构或接口值。
3. 检查 arg 的完整字段和动态类型：是否存在任意路径能回到 ptr。
4. 将清理需要的数据复制成独立值，优先传资源句柄、路径、ID 或不含回指的参数结构。
5. 把确定性释放放在显式方法或 defer 中，把 AddCleanup 当作兜底。
6. 对象最后一次使用后再考虑 KeepAlive，不要用它掩盖 cleanup 的反向引用。

常见问题

cleanup 里读取 ptr 的一个字段也不行吗？

不建议。只要闭包环境保留了能回到 ptr 的引用，就可能阻止目标对象变成不可达。应在注册前提取所需字段，传给 cleanup。

arg 是结构体就一定安全吗？

不一定。结构体是否安全取决于字段图，而不是值类型外观。结构体中只要包含指向 ptr 的指针、接口动态值或嵌套引用，就可能形成回指。

有了 AddCleanup，还需要显式 Close 吗？

需要。cleanup 的运行时机不确定，也不保证在进程退出前执行；它适合做遗漏路径的兜底，不能替代确定性资源管理。

归纳起来，AddCleanup 的关键不是“把清理代码挂到对象上”，而是把生命周期观察对象与清理所需数据彻底分离。只要 cleanup 和 arg 都不回指 ptr，再配合显式释放与必要的 KeepAlive，这项能力才不会因为闭包捕获而失去触发条件。