Go context.Cause 怎么保留取消原因：WithCancelCause、Err 与跨层传递

服务收到上游取消信号时，日志里经常只剩一句 context canceled，但真正触发它的原因可能是用户主动退出、熔断器拒绝，或是某个前置依赖提前失败。Go 1.20 引入的 context.WithCancelCause 可以把这个具体原因顺着调用链一路带到最末端；ctx.Err() 依然维持大家熟悉的 context.Canceled 或 context.DeadlineExceeded 语义，诊断类的细节信息单独通过 context.Cause(ctx) 读取。

为什么只记录 context canceled 不够用

这个场景日常开发里非常常见：HTTP 请求进入 LoadProfile，中途还要调用权限服务做校验。权限服务先返回了明确的业务错误，业务层为了快速回收资源主动调用了 cancel()，结果到了链路最上层，最终只能看到一个非常通用的取消错误，根本没法定位是哪里出了问题。

ctx, cancel := context.WithCancel(parent)
defer cancel()

if err := checkPermission(ctx); err != nil {
    cancel()
    return ctx.Err() // 只有 context canceled
}

这段代码的问题不在于主动取消的逻辑，而是把“取消这个动作发生”和“为什么要触发取消”两个完全不同的信息混成了同一个值。调用方通常需要用 errors.Is(err, context.Canceled) 做流程分支判断，打日志、埋指标的时候却还需要知道这次取消是 permission denied、upstream rejected 还是人工运维终止。

WithCancelCause、Err 和 Cause 各自负责什么

把 context 的创建方式换成 WithCancelCause，返回的取消函数签名会变成 func(error)。下面的示例代码会同时打印两个不同维度的结果：

package main

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

var ErrPermissionDenied = errors.New("permission denied")

func main() {
    ctx, cancel := context.WithCancelCause(context.Background())
    cancel(ErrPermissionDenied)

    fmt.Println(ctx.Err() == context.Canceled)
    fmt.Println(context.Cause(ctx) == ErrPermissionDenied)
}

// 输出：
// true
// true

第一行输出的是协议层面的状态：这个 context 已经进入取消状态。第二行输出的是诊断层面的根因：这次触发取消是权限检查失败导致的。两者不存在互相替代的关系，做服务边界设计的时候最好保留这两个维度的信息，不要丢其中一个。

跨层传递时，原因应该在哪里写入

建议在最接近“做出取消决策”的那一层写入 cause 字段，下游的业务函数只负责读取和包装即可。这样既不会让底层的数据库操作依赖知道上层的业务错误细节，也不会让最外层的日志逻辑凭空猜失败来源。

var ErrUpstreamRejected = errors.New("upstream rejected")

func Handle(ctx context.Context) error {
    child, stop := context.WithCancelCause(ctx)
    defer stop(nil)

    if err := callPolicyService(child); err != nil {
        stop(fmt.Errorf("policy check: %w", err))
    }

    

这里的 defer stop(nil) 只是用来兜底释放资源，不会覆盖已经提前写入的业务原因。真正的错误通过 stop(err) 显式写入，外层再用 errors.Is 或 errors.As 检查错误包装链就能拿到原始根因。

父子 context 同时取消时为什么不能覆盖原因

context 的取消动作是一次性的。如果父 context 先通过 ErrParent 触发取消，子 context 的 Cause 就会直接继承这次父级传递过来的原因；反过来，如果子 context 先以 ErrChild 触发取消，子分支会保留自己写入的独立原因，之后父级再触发取消也不会把它改掉。

parent, cancelParent := context.WithCancelCause(context.Background())
child, cancelChild := context.WithCancelCause(parent)

cancelChild(errors.New("child failed"))
cancelParent(errors.New("parent stopped"))

fmt.Println(context.Cause(child))  // child failed
fmt.Println(context.Cause(parent)) // parent stopped

这条特性对并发任务组场景尤其重要：如果多个 worker 共用同一个父 context，父级的 cause 只能表达“整个任务组为什么要停止”，不能自动替每个 worker 保存自己的局部错误。需要逐个收集 worker 错误的时候，应该单独设置错误通道，或者使用 errgroup 提供的错误模型。

三个容易误判的用法

把 Cause 当成 Err 的替代品

不建议直接把 context.Cause(ctx) 当成所有对外接口的返回错误。很多旧的调用方往往只认识 context.Canceled 和 context.DeadlineExceeded 这两个标准取消错误值。对外返回结果时可以继续保留标准的错误分类逻辑，单独把 Cause 写入日志的扩展字段即可。

用 nil 调用取消后期待得到业务错误

cancel(nil) 只是表示正常触发取消动作，它不会凭空生成自定义的业务原因；这个时候 Cause(ctx) 与 ctx.Err() 都会落到默认的取消状态。如果确实需要标注具体取消原因，请主动传入一个带有明确语义的 error。

认为子 context 会自动汇总所有并发错误

context 只会保存取消树上的第一个触发原因，它不是通用的错误聚合器。多个并发分支需要收集完整结果的时候，要用专门带错误收集能力的并发协调结构，不要试图把所有错误信息都塞进同一个 cause 里。

一个可执行的验收清单

• 标准流程判断逻辑是否仍使用 errors.Is(err, context.Canceled) 或 errors.Is(err, context.DeadlineExceeded)。
• 打印日志的时候是否同时记录了 ctx.Err() 和 context.Cause(ctx)，避免整条链路只剩一句通用的取消提示。
• 每个 WithCancelCause 生成的派生 context 是否在所有分支都调用了对应的取消函数，避免派生 context 长时间占用资源。
• 父子 context 并发取消的测试是否覆盖了“父先取消”和“子先取消”两种执行顺序。

相关问题

context.Cause 是从哪个 Go 版本开始有的？

context.Cause 与 WithCancelCause 从 Go 1.20 版本开始正式提供；如果项目需要兼容更早的 Go 版本，建议继续使用标准的 Err() 语义，或者在业务层单独维护取消原因字段。

超时也能记录自定义原因吗？

可以在 Go 1.21 及之后的版本使用 WithTimeoutCause 或 WithDeadlineCause，让超时事件触发时直接返回预设的 cause 值；手动调用它们返回的取消函数不会覆盖这个提前预设的超时原因。

为什么不直接把错误放进 context.Value？

Value 是用来跨 API 传递请求作用域的通用数据，不适合用来承载取消协议相关的信息。取消原因应该通过 Cause 来表达，业务层的错误结果还是要通过函数返回值或者专门的错误收集机制来传递。

把取消状态和诊断原因分开

日常开发里最稳妥的写法是：用 Err() 做流程判断，用 Cause() 辅助解释故障现场，用函数返回值承载最终需要交给调用方处理的业务错误。这样既不会破坏 Go 现有的 context 约定，也能让一条“请求被取消”的日志，清晰回答清楚它到底为什么会发生。