Go context.AfterFunc 怎么迁移：取消清理、Stop 竞态与测试边界

服务请求被取消时，持有的连接、锁等待状态或者临时分配的资源，通常都需要马上清理收尾。以前常见的写法是单独起一个 goroutine 监听 ctx.Done()；Go 1.21 提供的 context.AfterFunc 可以把这段取消回调直接挂载到上下文上，但迁移时最容易误判的是 stop() 的返回值：它只表示是否成功阻止了回调启动，不代表回调逻辑已经执行完成。

把 done 监听逻辑换成 AfterFunc 后，清理相关代码会更集中；要妥善处理竞态问题，必须给回调增加完成信号，并把 stop 返回 true、false 两条分支路径都覆盖测试到。

先看旧式 done 监听到底多了什么

假设请求处理期间要把连接的读截止时间提前到当前时刻，用来打断正在阻塞的读取操作。旧代码通常会开一个 goroutine 观察 ctx.Done()，主流程返回后再发信号让观察者退出：

func readPacket(ctx context.Context, conn net.Conn, buf []byte) (int, error) {
    stopped := make(chan struct{})
    go func() {
        select {
        case 

这段代码可以跑通，但资源生命周期分散在三个地方：监听 goroutine、读取动作和 stopped 的关闭逻辑。更麻烦的是，正常读取刚结束的瞬间，取消回调可能已经抢到调度权，如果这之后又要把连接状态重置，就会出现两个执行路径互相覆盖状态的问题。

用 context.AfterFunc 收拢取消动作

迁移的最小改动方案，是让 AfterFunc 负责触发截止时间修改，让主流程负责决定何时恢复连接状态。回调里增加一个完成信号，主流程在需要的位置等待这个信号即可：

func readPacket(ctx context.Context, conn net.Conn, buf []byte) (n int, err error) {
    cleaned := make(chan struct{})
    stop := context.AfterFunc(ctx, func() {
        defer close(cleaned)
        _ = conn.SetReadDeadline(time.Now())
    })

    n, err = conn.Read(buf)
    if stop() {
        // 回调还没有启动，连接仍由当前路径管理。
        return n, err
    }

    // 回调可能已经在独立 goroutine 中运行，先等它完成。
    

这里的判断逻辑不是“取消了就一定返回超时”，而是先确认 stop() 能否成功解除回调。如果返回 false，读取操作通常已经被取消动作打断，等待 cleaned 完成后再恢复连接状态，才能避免清理回调和正常业务路径同时修改连接属性。

Stop 的两个结果对应两种完全不同的时序

只把返回值写进代码注释远远不够，迁移时应该明确每个分支的职责边界：

尤其要注意，stop() 返回 false 之后不能直接假定回调一定已经执行完毕。官方文档明确说明它不会等待回调完成。只要回调会写连接、关闭文件、释放锁或者更新共享状态，就应当让回调主动关闭完成 channel，或者使用一个可等待的同步对象。

正常返回和取消回调不要各自释放一次

实际迁移里更常见的 bug，不是忘记注册回调，而是两条路径都执行了资源释放动作：

type cleanupGate struct {
    once sync.Once
    done chan struct{}
}

func (g *cleanupGate) closeConn(conn net.Conn) {
    g.once.Do(func() {
        _ = conn.Close()
        close(g.done)
    })
}

如果取消回调和正常返回都可能调用 closeConn，用 sync.Once 保证资源释放逻辑只执行一次；如果还需要等待释放流程完全结束，就把 close(g.done) 放在同一个临界区域内。不要只依赖“通常主流程会先返回”的经验判断，高并发压力下调度顺序并不固定。

迁移后的回归测试要覆盖取消前后两条路

测试重点不是检查回调函数恰好被调用一次这么简单，而是要验证资源状态和返回路径的正确性。至少要准备三组用例：

• 上下文没有被取消，读取操作正常完成，stop() 返回 true，连接状态不会被异步回调改写。
• 上下文先被取消，回调执行完成后返回 context.Canceled 或者 context.DeadlineExceeded，连接状态已经恢复完成。
• 让读取结束和取消动作同时发生，重复运行测试，确认没有数据竞争、重复关闭或者永久阻塞的问题。

可以在测试回调里注入一个受控 channel，不要用固定的 time.Sleep 作为同步手段。如果项目启用了竞态检测，迁移后至少完整运行一次 go test -race ./...；它不能证明所有时序都被覆盖，但可以快速暴露对共享连接状态的无保护读写问题。

这几类场景不适合直接替换

AfterFunc 适合“上下文取消时触发一次动作”的场景，不是所有后台循环的通用替代方案：

• 需要周期性触发的任务，仍然应该使用 ticker 或者明确的时间调度器实现。
• 回调必须在当前 goroutine 内完成的逻辑，不要把它放进 AfterFunc 之后再假定调用方会主动等待。
• 回调包含长时间网络操作时，要单独设计它自己的上下文和退出协议，不能把取消回调当成免费的后台线程随便用。

迁移前先梳理清楚资源的唯一拥有者：谁创建资源，谁在正常业务路径释放资源，取消时谁负责打断执行逻辑。拥有者边界不清晰时，直接替换 API 只会把竞态问题藏得更深。

常见问题

AfterFunc 的回调会阻塞调用 AfterFunc 的 goroutine 吗？

不会。回调会在独立的 goroutine 中执行；如果调用方需要知道回调何时结束，必须自行实现完成通知机制。

stop 返回 false 是不是说明回调已经执行完？

不是。它只说明回调没有被这次 stop 调用阻止，可能已经启动，也可能之前就已经被停止；要确认回调执行完成，等待回调发出的完成信号即可。

同一个 context 可以注册多个 AfterFunc 吗？

可以。多个注册的回调彼此独立，不会互相替换；每个注册都要单独保存自己的 stop 函数和对应的完成同步协议。

什么时候继续使用 done 监听更合适？

如果逻辑需要持续观察多个事件、复用一个长期存在的 goroutine，或者必须把所有状态转换放在同一个循环里，保留显式的 select 写法通常更直观。

迁移清单

1. 把取消动作限定为一次性资源清理，不要用来实现周期任务。
2. 为回调增加完成通知，尤其是它会修改共享资源的场景。
3. 分别处理 stop() == true 与 false 两个返回分支，不要把 false 当成回调执行完成。
4. 让正常路径和取消路径共享幂等的资源释放函数。
5. 用取消前、取消后、同时触发三组测试配合竞态检测完成验收。

这样迁移后，代码减少的不只是一个额外的 goroutine，更是把取消动作的归属、停止时序和资源回收结果整理成了可以逐条核对的明确协议。