用 context.AfterFunc 释放超时任务占用的资源

context.AfterFunc 适合处理这样一类超时任务：任务阻塞在连接、文件句柄、订阅或临时租约上，仅仅让 ctx.Done() 关闭还不足以唤醒底层调用。把资源关闭函数注册到 Context 后，超时发生时 Go 会在独立 goroutine 中执行回调，主动释放资源并促使阻塞操作退出。

可靠写法还需要覆盖正常完成。资源获取后立即注册回调；正常路径先调用 stop 解除关联，再进入同一个幂等 release；超时路径也只调用这个入口。最后由创建资源的 owner 等待清理结果，而不是让 AfterFunc 回调悄悄吞掉错误。

官方文档：https://pkg.go.dev/context#AfterFunc

超时信号不会自动释放业务资源

一个常见现场是：外层给任务设置了两秒超时，业务函数却仍卡在不感知 Context 的旧接口上。两秒后 ctx.Err() 已经是 context deadline exceeded，但文件描述符、连接或订阅仍被占用，等待任务的 goroutine 也没有退出。

Context 负责传播“应该停止”的信号，不负责猜测业务资源该怎么释放。只有底层 API 明确接受 Context，它才有机会主动响应；对于只提供 Close、Cancel、Rollback 或 Release 的资源，需要调用方把取消信号与释放动作关联起来。

先注册回调，再把资源交给阻塞任务

注册时机要靠近资源创建。如果先启动使用资源的 goroutine，之后才注册 AfterFunc，二者之间会出现一段没有清理保护的窗口。更稳妥的顺序是：建立超时 Context、获取资源、注册清理回调，最后才调用可能阻塞的工作函数。

回调本身应该短小，最好只执行本地、并发安全且能解除阻塞的动作。例如关闭连接、取消订阅或释放租约。不要在回调中反向等待业务任务退出，因为业务任务可能正在等资源关闭，两边会形成循环等待。

正常完成和超时共用一个 release

下面的包装函数把一个 io.Closer 的完整生命周期交给同一层管理。示例使用 WithTimeoutCause 保留超时原因，用 sync.Once 合并正常结束与超时回调，用带缓冲通道交付唯一一次 Close 结果：

package taskrun

import (
    "context"
    "errors"
    "fmt"
    "io"
    "sync"
    "time"
)

var ErrTaskTimeout = errors.New("任务超过允许时长")

func RunWithTimedResource(
    parent context.Context,
    timeout time.Duration,
    open func() (io.Closer, error),
    work func(context.Context, io.Closer) error,
) error {
    ctx, cancel := context.WithTimeoutCause(parent, timeout, ErrTaskTimeout)
    // 即使任务提前完成，也要释放 Context 自身持有的定时器资源。
    defer cancel()

    resource, err := open()
    if err != nil {
        return fmt.Errorf("获取任务资源: %w", err)
    }

    var once sync.Once
    cleanupResult := make(chan error, 1)
    release := func() {
        once.Do(func() {
            // 结果通道只由唯一释放者写入并关闭，owner 在返回前统一读取。
            cleanupResult 

这里不根据 stop() 的布尔值决定“谁负责清理”。无论回调是否已经开始，owner 都会调用同一个 release。如果回调先进入 once.Do，正常路径会等待它完成；如果 stop 成功阻止回调，正常路径就成为唯一释放者。

清理结果应该回到资源 owner

AfterFunc 回调没有返回值，直接在里面调用 Close 很容易丢掉错误。示例把关闭结果放进容量为 1 的通道，既不会让回调等待接收者，也能确保 owner 在函数返回前拿到结果。这里选择 errors.Join，是因为任务错误与清理错误可能同时有价值。

实际项目可以按资源类型调整策略：连接关闭失败通常记录并合并返回；事务回滚失败可能需要提升告警等级；临时文件删除失败可能进入后台回收队列。关键不是统一忽略或覆盖，而是由资源 owner 明确决定优先级。

三个竞争边界必须提前设计

第一，stop() == false 不等于回调已经完成。它可能表示 Context 已取消且回调开始，也可能表示关联此前已经停止。需要知道释放完成时，必须像示例一样显式协调。

第二，资源的释放动作必须适合并发场景。sync.Once 只保证包装函数执行一次，不会自动让一个本身会永久阻塞的 Close 变安全。释放函数应有明确上界，不能再依赖正在退出的业务 goroutine。

第三，正常路径不能只调用 stop 就返回。stop 成功只表示回调没有执行，资源仍需要由正常路径释放。也不能省略 defer cancel()；WithTimeout 返回的 CancelFunc 用来及时释放 Context 关联的定时器和父子引用。

远程收尾不要继续使用已超时的 Context

关闭本地句柄通常不需要 Context，但有些资源要调用远程接口注销租约、提交状态或写审计记录。此时直接复用已超时的 ctx，请求往往会立即失败。可以从原 Context 保留必要值，再建立一个短小、独立的清理时限：

func cleanupRemote(parent context.Context, revoke func(context.Context) error) error {
    // 保留请求值，但不继承已经发生的取消信号。
    base := context.WithoutCancel(parent)
    cleanupCtx, cancel := context.WithTimeout(base, 2*time.Second)
    // 独立清理 Context 也必须及时释放。
    defer cancel()

    return revoke(cleanupCtx)
}

这类远程补偿不宜直接塞进负责解除阻塞的 AfterFunc 回调。更稳妥的分工是：回调先完成本地释放，让主任务退出；owner 观察到任务结束后，再用独立短超时执行远程收尾。这样超时处理不会被第二个网络调用无限拖住。

相关问题

任务正常完成后还会执行 AfterFunc 吗？

如果 Context 之后被取消，而你没有调用 stop，回调仍可能执行。正常完成路径应停止关联并主动释放资源。

AfterFunc 能直接终止正在运行的 goroutine 吗？

不能。它只能运行你提供的函数。通常通过关闭底层连接、句柄或自定义停止通道，让阻塞操作自行返回。

为什么调用 stop 后还要调用 release？

stop 只管理 Context 与回调的关联，不负责业务资源。stop 成功时，恰恰意味着正常路径必须自己释放资源。

清理函数可以重新使用原来的 ctx 吗？

本地 Close 通常不需要；远程清理若需要 Context，应使用独立且有上界的清理 Context，避免复用已经超时的信号。