Go context.AfterFunc 怎样在取消时安排清理动作处理空输入并保留错误边界

context.AfterFunc 可以在 Context 取消后安排清理回调，但取消函数返回、回调开始、清理完成，是三个不同的观察点。想在函数返回前知道清理是否失败，需要自己保存错误并等待清理结束；仅调用 stop() 并不能满足这个要求。

我会把这个问题拆成“谁可以发起清理”和“谁负责等待结果”。下面给出一种小型封装，用 sync.Once 让正常返回与取消回调共享同一次清理。讨论的是代码设计取舍，不是实测记录，也不是新版本功能介绍。官方文档地址：https://pkg.go.dev/context#AfterFunc。

把取消清理看成单次收尾模式

这个模式可以叫单次收尾：Context 提供取消信号，AfterFunc 登记回调，sync.Once 约束实际释放只发生一次，finish 把结果交还给资源所有者。AfterFunc 自 Go 1.21 加入；它在独立 goroutine 调用回调，传入已取消的 Context 也会安排回调。多个登记互相独立，后登记的不会覆盖先登记的。

我更关心资源生命周期是否说得清，而不是有没有少写一行 defer。回调没有 error 返回通道，清理失败必须由业务封装另行传递。

适用压力来自两条收尾路径

典型压力是正常结束需要 release，取消也希望尽早 release，而且最终返回必须带上释放错误。直接在两处调用 release 会引入重复释放；只把 release 放进回调，正常完成时又可能永远等不到取消。

前提同样关键：release 必须允许与工作函数并发。例如某个资源明确支持并发关闭以中断阻塞操作，才适合提前触发收尾。若释放资源会破坏仍在读写的业务状态，应先让工作响应取消并停止，再由拥有者统一释放，不能直接套用这里的封装。

用同步结果保留清理错误

package cleanup

import (
    "context"
    "errors"
    "sync"
)

// Cleanup 在正常返回和取消回调之间共享一次清理及其结果。
func Cleanup(ctx context.Context, release func() error) (func() error, error) {
    if ctx == nil {
        return nil, errors.New("context 不能为空")
    }
    if release == nil {
        return nil, errors.New("release 不能为空")
    }
    var once sync.Once
    var cleanupErr error
    done := make(chan struct{})
    run := func() {
        once.Do(func() {
            // 发布错误后关闭通道，等待者在接收后读取错误。
            defer close(done)
            cleanupErr = release()
        })
    }
    stop := context.AfterFunc(ctx, run)
    finish := func() error {
        // stop 不等待回调；run 的 Once 负责与已启动回调同步。
        stop()
        run()
        

release 在 Once 的函数体内执行。done 是完成信号，cleanupErr 是错误槽位。finish 停止登记后仍调用 run：如果回调尚未执行，它自己完成清理；如果另一 goroutine 已经进入 Once，它会等待那次执行完成。接收 done 后读取错误，不让调用者在释放还没结束时读取共享结果。

这里不根据 stop 的布尔值判断“清理完成”。stop 返回 true 说明成功阻止回调运行；false 可能表示回调已启动，也可能是此前已经停止。两种返回值都不能替代完成同步。

// WithResource 只演示错误合并；release 必须允许与 work 并发。
func WithResource(ctx context.Context, work func(context.Context) error,
    release func() error) (err error) {
    if work == nil {
        return errors.New("work 不能为空")
    }
    finish, err := Cleanup(ctx, release)
    if err != nil {
        return err
    }
    defer func() {
        // 保留工作错误与清理错误，供调用者使用 errors.Is 判断。
        err = errors.Join(err, finish())
    }()
    return work(ctx)
}

第二段与第一段放在同一个包中，复用已有 imports；不是另一个独立文件的完整内容。errors.Join 保留工作错误与清理错误，二者均为 nil 时返回 nil。它需要 Go 1.20，而整个示例因 AfterFunc 至少需要 Go 1.21。调用者可对合并错误使用 errors.Is；错误字符串不能作为稳定协议。

空输入与取消竞争如何定界

这些是按代码与标准库契约推导的行为，不是本机运行输出。对已经取消的 Context，WithResource 仍会调用 work；若业务约定不得启动已取消任务，应在工作入口判断 ctx.Err()，同时接受检查后仍可能发生取消这一事实。

Cleanup 的参数检查失败时不会释放资源。因此获得资源的调用者必须先确保参数有效，或在构造失败路径自行归还资源。finish 可重复调用并取得同一个结果，但 release 不得递归调用 finish，否则会形成对自身完成的等待。

哪些反例不适合这个模式

第一个反例是把 stop 当成 join：stop 只解除登记，不等回调结束。第二个反例是在取消回调内拿一把工作线程持续持有的锁，而工作线程在锁内等待 finish；这样的相互等待会卡住返回。第三个反例是把可能无限阻塞的清理交给这个封装，再期待 Context 超时能让 finish 自动超时。

本封装故意等待 release 结束，没有额外的截止时间，也不会终止已经开始的清理。如果释放动作本身需要网络请求，应单独定义有界的清理策略；不要把已取消的 Context 直接当成清理操作唯一的可用上下文。

release 应通过 error 报告失败。这里没有 recover：回调 goroutine 中的 panic 不能靠工作函数外层 recover 捕获，通常会导致进程退出。sync.Once 也不会因为一次清理返回错误而自动重试，重试必须是清理操作自己明确支持的业务能力。

使用前的判断清单与常见问题

采用前先确认：释放可与工作并发；所有退出路径都调用 finish；清理不会递归等待自己；错误由返回值交给调用者；资源失败后的重试归属已经定义。只有正常返回时才需要释放的资源，直接 defer 通常更容易维护。

stop 返回 false，还能直接读清理错误吗？

不能。布尔值不是完成信号，应等待本文的完成同步，或使用其他明确的同步机制。

没有清理任务时一定要传 nil 吗？

本文接口拒绝 nil 函数，空操作应显式写成返回 nil 的函数。这样可以区分调用配置缺失与业务上无事可做。

AfterFunc 能替代 cancel 吗？

不能。AfterFunc 登记回调，不取消 Context。创建了可取消子 Context 的代码仍要在自己的生命周期内调用 cancel。

工作失败和释放失败只保留哪一个？

本文选择 errors.Join 同时保留。如果上层协议只接受一个错误码，应在协议转换层决定主错误，日志仍应记录另一项失败。

事实参考：context.AfterFunc 官方契约、sync.Once 官方文档、errors.Join 官方文档。