Go context 怎样传递可读取消原因

如果只调用 cancel()，下游通常只能知道“context 已取消”，却不知道是用户主动停止、上游失败，还是某个业务条件触发。Go 1.20 起，可以用 context.WithCancelCause 保存一个具体的 error，工作函数仍通过 ctx.Err() 判断通用状态，再用 context.Cause(ctx) 读取可读原因。

官方文档入口：https://pkg.go.dev/context。本文的核心边界是：Err 适合稳定分支判断，Cause 适合日志、诊断和上层解释；两者不是互相替代的两个错误返回值。

先分清 Err 和 Cause 各自回答什么

ctx.Err() 的结果仍然是 context.Canceled 或 context.DeadlineExceeded，便于调用方用 errors.Is 做稳定分支。context.Cause(ctx) 则返回第一次取消时记录的具体错误；如果没有通过 cause API 设置原因，它会回退到与 ctx.Err() 相同的值。

这两个值可以同时存在。例如底层任务因“配置热更新”被主动终止时，Err 仍表示取消，Cause 可以保留 config reload requested。不要只把 cause 当作新的成功/失败协议；它只是附着在取消信号上的诊断信息。

用 WithCancelCause 记录主动取消原因

WithCancelCause 的返回值与 WithCancel 类似，但取消函数类型变成 context.CancelCauseFunc。调用它时传入一个非空错误，后续从该 context 或其子 context 读取的 cause 就是这个错误；传入 nil 时，cause 会按文档表现为 context.Canceled。

package main

import (
    "context"
    "errors"
    "fmt"
)

var errReloadRequested = errors.New("config reload requested")

func main() {
    ctx, cancel := context.WithCancelCause(context.Background())
    defer cancel(nil) // 即使提前返回也释放 context 关联的资源。

    cancel(errReloadRequested) // 取消入口记录可读的业务原因。

    fmt.Println(ctx.Err() == context.Canceled) // 通用分类仍是 canceled。
    fmt.Println(context.Cause(ctx))             // 诊断信息是 errReloadRequested。
}

关键点是先保存返回的 context，再把 CancelCauseFunc 交给真正拥有取消权的代码。示例中的第二次 cancel(nil) 不会覆盖已经记录的原因；取消具有“第一次生效”的语义。

如果调用方只想表示普通取消，可以继续使用 WithCancel。只有当下游确实需要知道取消背景时，才把 cause 设计进接口，这样不会让每一层都被迫解析业务错误文本。

把取消原因交给实际工作函数

context 的价值在于沿调用链传播信号。工作函数应该接收 context.Context，在阻塞点监听 Done()，退出时再读取 Err 和 Cause。不要把错误写入全局变量，也不要用 context.Value 传递本来属于取消机制的诊断信息。

package main

import (
    "context"
    "errors"
    "fmt"
)

var errJobStopped = errors.New("job stopped by operator")

func waitJob(ctx context.Context) error {
    select {
    case 

上面的返回值故意只包装 ctx.Err()，因为这让 errors.Is(err, context.Canceled) 继续成立。日志或指标可以在边界处记录 context.Cause(ctx)；如果需要把原因同时带回调用方，应明确约定返回结构，而不是依赖错误字符串拼接。

父子 context 的首次取消不能事后覆盖

派生 context 会继承父级取消信号。父级先取消时，子级看到的是父级确定的 cause；子级先取消时，它自己的 cause 会固定下来，之后父级再取消也不会改写这次已经观察到的原因。这个规则能避免并发取消时日志出现“最后一次写入覆盖最初原因”的不稳定结果。

因此，拥有更具体业务信息的一层应该尽早决定是否创建 cause context。若父级只知道“请求结束”，子级知道“库存校验失败”，让子级先取消通常能保留更有用的诊断；如果请求级取消先发生，下游就只能看到请求级原因。

代码设计上不要让多个模块共享同一个取消函数并随意传入不同错误。可以把取消权限制在协调者手里，把只读的 context.Context 传给工作模块，这样原因的所有权更清楚。

主动取消和超时原因要分开设计

主动取消通常使用 WithCancelCause。如果是截止时间或超时触发，希望固定一个更易读的诊断原因，可以在 Go 1.21 及以后考虑 WithTimeoutCause 或 WithDeadlineCause。超时发生时，Err 仍用于识别 context.DeadlineExceeded，Cause 提供预先设置的解释。

package main

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

var errBudgetExceeded = errors.New("dependency budget exceeded")

func main() {
    ctx, cancel := context.WithTimeoutCause(
        context.Background(),
        200*time.Millisecond,
        errBudgetExceeded, // 超时后供 Cause 读取的固定原因。
    )
    defer cancel() // 手动提前结束时仍需释放定时器资源。

    

如果项目仍支持 Go 1.20，应继续使用 WithCancelCause 处理主动取消，或用普通 WithTimeout 让 Err 表达超时。不要只因为想打印一句更友好的话，就在低版本中调用不存在的 API。

上线前按这份清单检查

• 项目的最低 Go 版本覆盖正在使用的 cause API；WithCancelCause 从 Go 1.20 起提供，WithTimeoutCause 与 WithDeadlineCause 从 Go 1.21 起提供。
• 创建 derived context 后，在所有控制流路径调用 cancel 函数，避免定时器或子 context 生命周期延长。
• 分支判断优先使用 errors.Is(err, context.Canceled) 或 errors.Is(err, context.DeadlineExceeded)，不要比较错误文本。
• 日志字段记录 context.Cause(ctx) 时，避免把包含敏感数据的原始错误直接输出。
• 只把真正需要跨边界传播的取消原因纳入接口约定，普通取消不要强行包装业务错误。

实际迁移时，可以先给主动停止、父级请求结束、依赖超时三类场景分别定义有限的原因值，再决定哪些原因进入日志和指标。这样读者看到的不是一串任意错误文本，而是稳定的取消语义加上可读解释。

两个容易混淆的问题

调用 cancel(nil) 后 Cause 是什么？ 对通过 WithCancelCause 创建的 context，传入 nil 会把 cause 表现为 context.Canceled。如果 context 还没取消，Cause 返回 nil。

能不能用 Cause 替代 Err？ 不建议。Cause 适合诊断，Err 是跨包更稳定的取消分类；业务代码可以同时读取，但不要要求每个下游都认识所有上游自定义错误。

总结一下：用 WithCancelCause 记录原因，用 ctx.Err() 做通用分类，用 context.Cause(ctx) 做诊断，并让最具体、最先发生的取消原因拥有清晰的所有权。