Go runtime.AddCleanup 怎样处理空值和异常分支

我第一次把 runtime.AddCleanup 放进资源包装器时，真正耗时间的不是写出这一行调用，而是把异常分支分清：ptr 为空时应该在业务层返回错误，清理函数不能反向抓住目标对象，底层资源打开失败时不能留下一个半初始化对象，而 GC 兜底也不能被当成“程序退出前一定会执行”的承诺。

官方地址：https://pkg.go.dev/runtime

把 AddCleanup 当成资源回收的最后一道保险，显式 Close 才是正常路径。先处理 nil 和打开错误，再注册一个只接收独立资源句柄的 cleanup，能让异常分支变成可读的错误或可预期的 panic，而不是把问题推迟到 GC。

先用分支基线把结果说清楚

runtime.AddCleanup 是 Go 1.24 引入的运行时能力。它把 cleanup 绑定到一个对象：对象不再可达后，运行时可能在独立 goroutine 中调用 cleanup(arg)。这里的关键不是“能不能写”，而是每条分支的结果是否明确。

这个表也给出了一个简单的性能基线：正常使用时，资源的确定性关闭只有一条主路径；异常输入在注册前结束，不应额外启动清理 goroutine 或制造半成品对象。

把 nil 输入挡在 AddCleanup 之前

官方运行时代码会在 ptr == nil 时直接 panic，错误信息是 runtime.AddCleanup: ptr is nil。这不是普通的业务校验错误，而是 API 的参数契约被破坏。因此，面向调用方的构造函数应先判断资源或包装对象是否成立，不能把 recover 当成参数校验器。

另一个容易忽略的空值是 cleanup 参数。一个指针类型的 arg 可以是 nil，但 cleanup 是否能处理 nil 要由包装器自己保证；如果 nil 代表“没有可关闭资源”，更好的做法是在注册前结束流程，或者让清理函数成为显式安全的 no-op。下面先把构造入口写得保守一些：

package resource

import (
    "errors"
    "fmt"
    "os"
    "runtime"
)

var ErrEmptyPath = errors.New("资源路径不能为空")

// FileHandle 保存独立的文件句柄，不把 cleanup 设计成业务错误通道。
type FileHandle struct {
    file    *os.File
    cleanup runtime.Cleanup
}

// OpenFile 先处理输入和打开错误，只有资源确实存在时才注册 cleanup。
func OpenFile(path string) (*FileHandle, error) {
    if path == "" {
        return nil, ErrEmptyPath // 空输入在运行时 API 之前结束
    }

    file, err := os.Open(path)
    if err != nil {
        return nil, fmt.Errorf("打开资源失败: %w", err) // 不创建半初始化包装器
    }

    handle := &FileHandle{file: file}
    handle.cleanup = runtime.AddCleanup(handle, closeFile, file)
    return handle, nil
}

// closeFile 只接收独立句柄；nil 代表没有动作，避免清理路径再次 panic。
func closeFile(file *os.File) {
    if file == nil {
        return
    }
    _ = file.Close() // 兜底阶段无法把关闭错误返回给原调用方
}

这里的 handle 非空，file 也已经成功打开，调用 AddCleanup 的前置条件因此很直观。若文件打开失败，返回值中没有隐藏的 cleanup，也没有需要调用方猜测的“是否已经注册”状态。

让 cleanup 参数与目标对象断开

AddCleanup(ptr, cleanup, arg) 最重要的约束是：目标对象不能通过 cleanup 闭包或 arg 重新可达。比如把 handle 直接作为第三个参数，或者在闭包里引用外层的 handle，都会让“对象已经不可达”这个前提失效；第三个参数恰好等于 ptr 时，运行时还会主动 panic。

所以示例中传入的是独立分配的 *os.File，清理函数是包级函数，不捕获 handle。这条关系可以压缩成一句话：cleanup 只拿到“要释放什么”，不要拿到“谁负责管理它”。

// badRegistration 展示两个不应采用的注册方式，仅用于说明原因。
func badRegistration(handle *FileHandle) {
    // 错误：arg 等于 ptr，运行时会 panic，cleanup 不可能让 handle 变得不可达。
    _ = runtime.AddCleanup(handle, func(_ *FileHandle) {}, handle)
}

// goodRegistration 把资源句柄作为参数，cleanup 不引用外层包装器。
func goodRegistration(handle *FileHandle) {
    if handle == nil || handle.file == nil {
        return // nil 由调用方分支处理，不交给运行时注册
    }
    file := handle.file
    _ = runtime.AddCleanup(handle, closeFile, file) // file 与 handle 是两个对象
}

第二个函数只用于展示关系，真实代码不应该对同一个包装器重复注册相同的清理职责。若资源结构体把文件句柄嵌在同一个分配块里，也不要把指向该块内部的指针作为参数；这种参数关系会让目标对象无法按预期回收，某些情况还会在注册阶段 panic。

把异常打开和重复关闭收口

正常关闭应当先 Stop，再清空包装器里的句柄，最后执行底层 Close。这样做有两个结果：显式路径不会再等 GC，后续重复调用不会再次关闭同一个句柄；如果调用方完全忘记 Close，对象最终不可达时仍有机会走兜底。

// Close 是确定性释放入口，调用方应优先 defer 它。
func (h *FileHandle) Close() error {
    if h == nil {
        return nil // 允许 nil 接收者安全收口错误分支
    }

    h.cleanup.Stop() // h 在本次调用中仍可达，取消尚未排队的 cleanup
    file := h.file
    h.file = nil
    if file == nil {
        return nil // 重复 Close 不制造新的异常
    }
    return file.Close() // 只有显式路径能把关闭错误交给调用方
}

// ReadAllFile 演示构造失败和使用期错误都沿普通 error 返回。
func ReadAllFile(path string) ([]byte, error) {
    handle, err := OpenFile(path)
    if err != nil {
        return nil, err // 空路径或打开失败不会注册 cleanup
    }
    defer func() {
        _ = handle.Close() // 关闭错误在此示例中不改变读取结果
    }()

    data, err := io.ReadAll(handle.file)
    runtime.KeepAlive(handle) // 确保最后一次使用资源后包装器仍然可达
    if err != nil {
        return nil, fmt.Errorf("读取资源失败: %w", err)
    }
    return data, nil
}

上面的完整示例还需要在 import 中加入 io。这里特意把读取错误、打开错误和关闭动作放在普通控制流中；cleanup 不能返回错误，也不应该承担业务日志、重试或事务提交。

为非确定性设置边界

即使注册成功，也不能把 cleanup 当成同步回调。它可能与业务 goroutine 并发运行，多个 cleanup 之间没有规定顺序，而且官方文档明确说明 cleanup 不保证在进程退出前执行。runtime.GC 最多帮助把不可达对象的 cleanup 排进队列，并不等于已经等待清理函数执行完成。

如果方法的最后一次使用可能让接收者提前变得不可达，就在之后调用 runtime.KeepAlive。如果显式 Close 需要保证 cleanup 尚未排队，调用 Stop 时必须确保传给 AddCleanup 的目标仍然可达。对于会被多个 goroutine 同时调用的包装器，还要额外加锁或使用 sync.Once；AddCleanup 不会替业务代码解决并发关闭。

可以按下面的顺序做落地检查：

1. 构造函数先拒绝空路径、空配置或 nil 依赖，返回带上下文的 error。
2. 底层资源打开失败时立即返回，不创建半初始化对象。
3. cleanup 只接收独立的文件句柄、整数描述符或字节切片，不接收包装对象自身。
4. 显式 Close 先 Stop，再释放句柄；关键的关闭错误由显式路径返回。
5. 需要保证的动作放在普通控制流里，不能依赖进程退出时的 GC。

什么时候应该不用 AddCleanup

如果资源的生命周期已经能用 defer、所有权转移或明确的服务关闭钩子表达，就没有必要为了“保险”再增加 cleanup。它更适合包装容易被遗忘的底层资源，例如内存映射、外部句柄或低层缓存条目，而且必须接受执行时机不确定这一事实。

Go 官方在 Go 1.24 发布说明中把 AddCleanup 定位为比 SetFinalizer 更灵活的机制，但这并不意味着它能替代显式资源管理。性能上，正常路径只保留一次显式关闭；异常路径在注册前结束；GC 兜底只承担遗漏释放的尾部风险，这就是这个包装器比较稳定的成本边界。

小结

处理 runtime.AddCleanup 的空值和异常分支，可以记住四句话：ptr == nil 在业务层提前返回；cleanup 和 arg 不能反向持有目标；打开失败不创建半对象；显式 Close 是主路径，GC cleanup 只是兜底。把这四条写进构造函数和关闭方法，代码的错误边界就比单独添加一行运行时调用清楚得多。

常见问题

AddCleanup 的 ptr 传 nil 会返回 error 吗？

不会。运行时会直接 panic，因此面向业务的构造函数应在调用前判断 nil 或无效输入，不能用 recover 代替正常的错误设计。

第三个参数可以传 nil 吗？

如果参数类型允许 nil，传 nil 本身不等于把目标对象传回 cleanup；但清理函数必须明确处理 nil。对资源包装器来说，更推荐只在资源创建成功后注册，并让 cleanup 对空句柄安全返回。

为什么 cleanup 闭包不能引用外层对象？

闭包如果保存了目标对象，目标就可能一直可达，运行时无法按预期触发清理。把独立资源作为 arg 传入，并使用不捕获包装器的函数，可以切断这条引用链。

调用 Stop 后还会执行 cleanup 吗？

Stop 只对尚未排队的 cleanup 有效。如果 cleanup 已经因为对象不可达进入执行队列，Stop 不会撤回它；显式关闭仍应保持幂等。