Go runtime.AddCleanup 怎样组合到一个小型工具中

如果一个小型 Go 工具包装了文件描述符、临时目录或外部句柄，最稳妥的组合不是“等 GC 自动释放”，而是把 Close 作为主路径，再把 runtime.AddCleanup 放在对象被遗忘后的兜底位置。这个 API 从 Go 1.24 开始提供，清理函数会在对象不可达后的某个时间点异步执行，所以它不能替代 defer Close()，也不能承担必须在进程退出前完成的动作。

先把资源边界和失效路径分开

这个小工具假设每个句柄都有一个整数资源标识。正常使用者拿到对象后调用 defer h.Close()；真正的风险路径是调用方忘了关闭、对象丢失引用，或者 Close 与清理回调同时接近执行。我们要保护的资产是“底层资源只释放一次”，而不是追求某次 GC 一定马上回调。

因此，构造函数负责注册兜底，Close 负责业务确定性，独立状态负责两条路径的汇合。回调只拿到状态对象，不要在闭包中引用 h，否则回调可能反过来让宿主对象保持可达，清理永远没有机会运行。

用独立状态对象承载清理参数

package leasebox

import (
    "fmt"
    "runtime"
    "sync"
)

// releaseState 不保存 Handle 指针，避免 AddCleanup 的参数反向延长宿主生命周期。
type releaseState struct {
    once sync.Once
    id   int
}

// Handle 是一个需要显式关闭、同时带 GC 兜底的小型资源包装器。
type Handle struct {
    state   *releaseState
    cleanup runtime.Cleanup
}

// release 只接收独立状态；once 让 Close 与 GC 回调共享同一条幂等路径。
func release(state *releaseState) {
    state.once.Do(func() {
        // 这里替换成真实的 close、Remove 或释放句柄调用。
        fmt.Printf("release resource %d\\n", state.id)
    })
}

// New 创建资源包装器。Go 1.24+ 才能使用 runtime.AddCleanup。
func New(id int) *Handle {
    state := &releaseState{id: id}
    handle := &Handle{state: state}

    // 回调不捕获 handle；arg 只携带释放所需的独立状态。
    handle.cleanup = runtime.AddCleanup(handle, release, state)
    return handle
}

// Close 是调用方应优先使用的确定性释放入口。
func (h *Handle) Close() {
    if h == nil {
        return
    }

    // Stop 只保证移除尚未入队的 cleanup，release 仍需保持幂等。
    h.cleanup.Stop()
    runtime.KeepAlive(h)
    release(h.state)
}

这段组合有三个关键点。第一，state 没有回指 Handle，所以清理参数不会让宿主重新变得可达。第二，sync.Once 同时保护显式关闭和回调，即使 Stop 发生在清理已经入队之后，也不会重复释放。第三，KeepAlive 放在 Stop 后面，明确保证传给 AddCleanup 的对象在取消动作期间仍然可达。

把主路径、兜底路径和审计信号分开

在实际小工具中，使用方式应保持普通资源管理的习惯：

func run() error {
    h := New(42)
    defer h.Close() // 主路径：函数返回时确定性释放资源

    // 这里执行依赖 h 的工作；不要把 h 的引用藏进清理回调。
    return nil
}

如果调用者忘记 Close，GC 只会在判断对象不可达后排队回调；不要在生产逻辑中依赖手动 runtime.GC() 来触发结果。需要观察兜底是否积压时，可以读取 runtime/metrics 中与 /gc/cleanups/queued:cleanups 和 /gc/cleanups/executed:cleanups 相关的指标，把它们当作排查信号，而不是业务成功回执。

四个边界决定它是否适合你的工具

• 不保证退出前执行：临时文件最终删除、事务提交、消息确认等关键动作必须走显式 API。
• 不保证顺序：多个对象的清理可能并发发生，存在依赖关系时应在同一个显式 Close 中编排。
• 不适合长耗时回调：清理回调与用户 goroutine 并发运行，重活应交给可管理的后台任务，并保留关闭和超时策略。
• 注意对象形态：零大小对象、包级初始化对象和极小的无指针对象存在文档明确的不可保证场景；不要把它们当成可靠的资源锚点。

最后可以用一个简单的验收清单收口：正常路径是否总有 defer Close；回调是否只接收独立状态；释放是否幂等；依赖顺序是否由显式方法处理；指标是否能暴露 queued 与 executed 的长期差距。满足这些条件时，runtime.AddCleanup 才是安全网，而不是生命周期的唯一控制器。

常见疑问

可以直接把 h 传给清理函数吗？不建议。它会让清理参数持有宿主对象，可能使对象始终可达；应传入不回指宿主的资源标识或独立状态。

Cleanup.Stop 后还需要幂等保护吗？需要。清理如果已经入队，Stop 不会撤回它；显式关闭和兜底必须共享一次性释放逻辑。