Go context.AfterFunc 回调与取消同时发生时怎样保证只清理一次

把正常结束、defer 和 context.AfterFunc 回调中的实际清理动作放进同一个 sync.Once，就能让这些入口竞争时只执行一回清理函数。收尾时先调用 stop 解除尚未触发的回调，再调用这个共享清理入口；不要把 stop 返回 false 理解成“清理已经完成”。

AfterFunc 自 Go 1.21 提供，用来把取消通知关联到一个独立 goroutine 中的函数。这里解释这一能力如何接入已有收尾代码，不涉及某次新版本的行为变更。官方文档地址：https://pkg.go.dev/context#AfterFunc，同步原语说明：https://pkg.go.dev/sync#Once。

最小写法：所有入口共享一个清理函数

原来正常路径里有一次释放、错误返回的 defer 里又有一次释放，加入取消回调后就多了一个并发入口。不能给每个入口分别创建 Once：必须针对同一份资源共享同一个实例。下面是可放在函数内部的核心片段，cleanupBody 表示该资源的实际清理函数。

// once 与资源一一对应，不能在不同入口各建一份。
var once sync.Once
cleanup := func() {
    once.Do(cleanupBody)
}
stop := context.AfterFunc(ctx, cleanup)
defer func() {
    // 解除关联不等于等待；共享入口负责执行或等待实际清理。
    stop()
    cleanup()
}()

如果正常收尾先执行，cleanup 会完成实际动作；如果回调正在执行同一个 Once.Do，正常收尾的调用会等它返回。这里等待的是 Once 中的清理函数，不意味着整个回调包装函数已经退出。只在实际动作正常返回的前提下，才能把 cleanup 返回解释成这一轮清理已完成。

为什么还要 stop：解除注册与清理是两件事

AfterFunc 不会替换同一个 context 上其他已注册的回调。已经取消的 context 也会让新注册的函数在独立 goroutine 中被调用，所以不能假设“注册返回前回调绝不开始”。需要的共享状态应先准备好，再注册。

不根据 stop 的布尔值决定是否调用共享 cleanup，可以避免漏掉正常路径的清理，也避免对 false 的含义做过度推断。即便 stop 已经被其他代码调用过，这一写法仍然通过同一 Once 收尾。

对旧代码的影响：一次执行不等于可以随时关闭资源

原先只有函数返回时释放资源，业务代码可能默认使用期间资源一直有效。改成取消回调也能触发清理后，释放可能与正在执行的业务操作重叠。sync.Once 只协调多个清理调用，不协调业务读写。接入前应确认资源接口允许并发关闭，或通过自己的锁、所有权交接及业务结束信号避免冲突。

不要在持有清理函数所需的锁时等待 cleanup，也不要在 cleanupBody 内再次调用同一个 cleanup；后者会等待自己，造成死锁。清理函数若可能阻塞，收尾也会跟着等待，Once 不会自动增加超时。

迁移示例：让取消与正常收尾竞争

下面的完整程序用输出代表清理副作用，不依赖文件或网络资源，也不声称模拟真实资源的并发关闭能力。cancelDone 只负责等待演示用的取消 goroutine 退出；实际清理由共享 Once 约束。

package main

import (
    "context"
    "fmt"
    "sync"
)

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    var once sync.Once
    cleanup := func() {
        once.Do(func() {
            // 实际项目在这里执行同一份资源的清理动作。
            fmt.Println("cleanup")
        })
    }

    // 共享状态已就绪，回调与正常收尾使用同一入口。
    stop := context.AfterFunc(ctx, cleanup)
    cancelDone := make(chan struct{})
    go func() {
        defer close(cancelDone)
        cancel()
    }()

    // 不依赖谁先获得调度，也不根据 stop 的真假跳过清理。
    stop()
    cleanup()
    

按这些接口语义推导，预期输出如下；示例未指定回调和正常收尾谁先赢得竞争：

cleanup
cleanup finished

如果取消触发回调，回调和主 goroutine 会争用同一个 Once；如果 stop 抢先解除关联，则主 goroutine 完成清理。两种情况都不要求读取 stop 的返回值。程序表达的是同一个副作用只执行一回，不是证明所有可能的资源类型都能安全这样关闭。

最小判断与常见问题

迁移时需要看三个边界：Once 是否属于这份资源、所有释放入口是否都调用同一个 cleanup、调用者等待的究竟是实际清理还是整个回调。只需要清理完成时，前面的写法已利用 Once.Do 的等待语义；如果回调在 cleanup 外还有操作，应额外设计完成通知，不能拿 stop 当 join。

回调里 close(done)，stop 后直接等 done 可以吗？

不能无条件这么做。如果 stop 成功，回调不会运行，也就没人关闭这个 channel。完成通知必须覆盖“回调被阻止”的分支，或者把通知和实际清理放在共享的一次性动作中。

Once 能保证清理成功吗？

不能。它限制函数执行次数，不提供错误重试。若动作返回错误，应明确记录和上报；需要重试的释放协议不能简单依靠同一个 Once 再执行。发生 panic 后，Once 也不会再次调用该动作。

多个 AfterFunc 注册同一个 context 会自动只运行一个吗？

不会，它们互相独立。若确实管理同一份资源，应共享清理入口；若是不同资源，各自管理，不要用全局 Once 把其他资源的清理一并跳过。

参考：context.AfterFunc 官方文档；sync.Once.Do 官方文档。