context.AfterFunc 注册超时清理回调的使用边界

context.AfterFunc 适合给一个会被取消的 Context 挂上“取消后做什么”的回调。它不是同步的超时钩子：回调会在独立 goroutine 中运行，返回的 stop 函数也不会等待回调结束。真正容易出错的地方，是把“停止关联”“回调已经执行完”和“资源只清理一次”混成了同一件事。

本文只围绕超时清理这一小块展开：先看它什么时候触发，再处理 stop 的竞态，最后判断哪些清理动作值得交给它。

结论：用 AfterFunc 注册取消后的补偿动作，用幂等函数合并主动结束和超时结束；若调用方必须等清理完成，就额外建立完成信号，不能只看 stop() 的返回值。

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

context.AfterFunc 到底在什么时候执行

AfterFunc(ctx, f) 会把 f 绑定到 ctx 的取消信号。WithTimeout 到期时，Context 被取消，回调才会被安排执行；如果传入的 Context 已经取消，回调也会被安排执行。这里的“安排”很关键：它不是在调用 AfterFunc 的 goroutine 里同步运行。

一个常见模型是：主流程负责等待请求或任务结束，回调负责释放与取消信号绑定的辅助资源。

package main

import (
	"context"
	"fmt"
	"time"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 80*time.Millisecond)
	defer cancel() // 无论是否超时，都释放定时器和子 Context 引用

	done := make(chan struct{})
	stop := context.AfterFunc(ctx, func() {
		defer close(done) // 给需要等待清理完成的调用方一个明确信号
		fmt.Println("执行超时后的清理")
	})

	_ = stop // 生产代码中要根据任务是否提前完成决定何时调用它
	

如果上层主动调用了 cancel，结果与超时到期相同：回调只关心 Context 已取消，并不区分是谁触发的。若业务必须区分“用户取消”和“超时”，应该在回调中读取 ctx.Err()，或者在更上层保存明确的业务原因。

stop 返回值决定了清理竞态怎么收口

注册函数返回的 stop 是一个“解除关联”的函数。调用它返回 true，表示回调尚未开始且关联被成功停止；返回 false，表示 Context 已取消、回调可能已经开始，或者这个回调此前已经被停止。无论哪种情况，stop 都不会等待 f 返回。

因此，正常完成路径和超时路径不要各写一套互不知情的释放代码。把资源释放收进一个幂等函数，再用完成信号解决“回调是否已经收尾”的问题：

import (
	"context"
	"sync"
)

func watch(ctx context.Context, release func()) {
	var once sync.Once
	finished := make(chan struct{})

	cleanup := func() {
		once.Do(func() {
			defer close(finished) // 无论谁先触发，都只广播一次完成
			release()             // 这里必须能安全地被并发路径调用
		})
	}

	stop := context.AfterFunc(ctx, cleanup)
	defer func() {
		if stop() {
			cleanup() // 没有等到取消回调时，由正常结束路径补做清理
		}
		

上例的重点不是固定使用 sync.Once，而是把两个事实分开：once 保证释放动作只发生一次，finished 保证需要等待的人能知道回调已经退出。若 release 本身可能阻塞，还要评估它是否应该放在请求链路上执行。

哪些清理动作适合交给 AfterFunc

它适合做“取消发生后才有意义”的补偿，例如唤醒等待条件、撤销辅助注册、关闭只服务于当前任务的临时资源。回调必须自行处理并发，因为它在独立 goroutine 中执行；同一个 Context 上注册多个回调时，它们也彼此独立，不会互相覆盖。

下面几类情况要谨慎：

几个容易混淆的问题

AfterFunc 是定时器吗？不是。它监听的是 Context 的取消；只有当 Context 本身由 WithTimeout 或 WithDeadline 产生时，才表现为“超时后回调”。

调用 stop 后能保证回调没执行吗？只有返回 true 才表示本次调用成功阻止了回调启动；返回 false 时不能据此判断回调是否已经完成。

回调里能直接改共享状态吗？可以，但必须按并发代码处理，使用锁、原子操作或单次清理协议保护共享状态。最稳妥的判断是：把 AfterFunc 当作一个额外的并发参与者，而不是当前函数的 defer。

如果你的任务只有“函数返回时释放资源”这一条路径，defer 更直观；如果资源需要在 Context 取消时被唤醒或撤销，AfterFunc 才有明确价值。把触发、只执行一次和等待完成分别设计，超时清理就不会因为一个布尔返回值而变得含糊。