Go context.Cause 如何保留取消根因

当一个 Go 请求被取消时，ctx.Err() 通常只能告诉你“已取消”还是“已超时”，排查日志时还缺少真正触发取消的业务原因。需要保留这个根因时，应在创建派生上下文时使用 context.WithCancelCause，调用返回的 CancelCauseFunc 写入一个 error，下游再用 context.Cause(ctx) 读取它。

Cause 与 Err 是两层信息：前者保留具体错误，后者提供稳定的通用状态。比如主动取消时，ctx.Err() 仍然是 context.Canceled，而 context.Cause(ctx) 可以是 errUpstreamRejected。这一组 API 从 Go 1.20 起提供，官方文档：https://pkg.go.dev/context。

先把通用状态和业务根因分开

传统的 context.WithCancel 返回普通 CancelFunc，它只能发出取消信号。调用方在下游看到的通常是 context.Canceled，无法直接知道是上游拒绝、请求撤回，还是服务关闭导致的取消。

context.WithCancelCause 的返回值仍然是一个可取消的派生 Context，但第二个返回值变成了 CancelCauseFunc。调用它时传入的非 nil error 会成为这个 Context 的取消原因；调用 context.Cause 时可以把这条原因取回来。

因此，业务代码不应把 Cause 当成另一个版本的 Err。如果只需要判断是否结束，可以继续检查 ctx.Err()；如果要保留为什么结束，就在同一条取消链上读取 context.Cause(ctx)。

用 WithCancelCause 把根因放进取消链

实际接入时，创建取消上下文的一方通常拥有停止这段工作的责任。它定义可比较的错误值，调用 cancel(cause)，再把 Context 交给 worker。worker 不需要知道根因是由哪一层产生的，只要在结束分支读取 Context 的状态即可。

package main

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

var errUpstreamRejected = errors.New("upstream rejected the request")

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

这段代码只展示 API 关系，没有在本文中执行。按照官方语义，ctx.Err() 是 context.Canceled，context.Cause(ctx) 是 errUpstreamRejected。如果取消原因要参与业务判断，优先用 errors.Is 或 errors.As，不要只比较错误字符串。

把 Context 传下去，别把根因复制成另一个参数

取消原因属于取消链的生命周期信息，适合随着 Context 传递到真正执行工作的边界。函数仍应把 Context 放在第一个参数位置，worker 根据自己的职责读取 Done、Err 和 Cause，而不是把原因单独塞进全局变量或结构体字段。

func handle(ctx context.Context, load func(context.Context) error) error {
    if ctx == nil || load == nil {
        return errors.New("context and load function are required") // 先拒绝无效输入。
    }
    if err := load(ctx); err != nil {
        // 下游已经返回业务错误时，保留它本身，不用 Cause 覆盖真实失败。
        return err
    }
    if cause := context.Cause(ctx); cause != nil {
        // 业务成功但上下文后来取消时，记录取消根因供上层归因。
        return fmt.Errorf("request canceled: %w", cause)
    }
    return nil
}

上面的示例刻意把“下游业务失败”和“Context 取消”分开。Cause 只解释取消链，不会自动解释任意函数返回的错误；如果下游已经返回了数据库、网络或参数错误，就不应无条件用 context.Cause 把它替换掉。

如果需要记录日志，可以同时写入一个稳定分类和根因信息：分类用 errors.Is(ctx.Err(), context.Canceled) 或 errors.Is(ctx.Err(), context.DeadlineExceeded)，诊断字段使用 context.Cause(ctx)。这样既便于聚合，也不会丢掉原始错误身份。

父子 Context 的首次取消决定根因

取消原因不是每次调用 cancel 都会覆盖的可变字段。官方规则是：Context 自身或它的父级第一次取消时，原因就被确定。父级先取消，子级会看到父级原因；子级先取消，子级可以保留自己的原因，而父级仍有自己的原因。

func firstCancellationWins() {
    parent, cancelParent := context.WithCancelCause(context.Background())
    defer cancelParent(nil) // 兜底释放父级；首次取消后不会覆盖已有原因。

    child, cancelChild := context.WithCancelCause(parent)
    defer cancelChild(nil) // 同样只在 child 尚未取消时生效。

    childCause := errors.New("child stopped first")
    parentCause := errors.New("parent stopped later")
    cancelChild(childCause)  // 子级先取消，child 保留自己的原因。
    cancelParent(parentCause) // parent 仍记录自己的首次取消原因。

    fmt.Println("parent cause：", context.Cause(parent))
    fmt.Println("child cause：", context.Cause(child))
}

这里的关键不是哪个函数写在前面，而是哪一个 Context 先进入取消状态。在反过来的场景中，如果先调用 cancelParent(parentCause)，子级会继承 parentCause，之后再调用 cancelChild(childCause) 也不能把已经传播到子级的原因改掉。

调用 cancel(nil) 也不是“没有原因所以保持未取消”。WithCancelCause 会把 nil 处理为 context.Canceled；在设计上不需要更具体原因时，可以这样使用，但不要把它当成等待以后补写错误的占位操作。

超时原因要用对 WithTimeoutCause

如果根因来自一个明确的 deadline，而不是业务代码主动决定取消，可以考虑 context.WithTimeoutCause 或 context.WithDeadlineCause。它们在 deadline 到期时为返回的 Context 提供预先指定的原因，适合把“这项工作因预算耗尽而停止”与普通主动取消区分开。

func withTimeoutCause(parent context.Context) (context.Context, context.CancelFunc) {
    // 该片段依赖 context、errors 和 time 标准库包。
    timeoutCause := errors.New("worker budget exhausted")
    ctx, cancel := context.WithTimeoutCause(parent, time.Second, timeoutCause)
    // 返回 CancelFunc 的一方仍要在工作结束时调用它，及时释放定时器资源。
    return ctx, cancel
}

WithTimeoutCause 返回的是普通 CancelFunc，传给它的原因用于 deadline 到期，不是让调用者在手动 cancel() 时再传一个错误。若业务需要在主动取消时动态写入原因，应选择 WithCancelCause；若是超时到期的固定归因，再选择 WithTimeoutCause。

无论采用哪一种 API，都要保留 defer cancel() 或等价的释放路径。取消函数不会强制终止不观察 Context 的任意代码，它只是关闭取消信号并释放 Context 相关资源；真正的 worker 仍必须在阻塞点观察 Done。

日志和业务判断各自读取什么

接入后可以按下面的边界整理处理逻辑：先判断 Context 是否已结束，再判断结束类别，最后把具体原因作为诊断信息记录。不要把 context.Cause(ctx).Error() 当作唯一业务协议，也不要把所有原因都转成字符串后再判断。

这套分层对重试尤其重要：是否重试通常取决于业务错误类型和取消类别，不是看到任何 Cause 就重试。请求被上游明确撤回时，重试可能只会重复已经被拒绝的工作；预算到期时，也应先确认下游是否具备幂等性和新的预算。

Cause 在 Context 尚未取消时返回什么？

返回 nil。它不是预先保存任意业务错误的通用容器，只有 Context 或其父级发生取消后，才能读取取消根因。

Cause 会覆盖 ctx.Err 吗？

不会。主动取消时，Err 仍提供 context.Canceled，Cause 额外提供更具体的 error；两个结果服务不同的判断层。

多次调用 CancelCauseFunc 会保留最后一次原因吗？

不会。首次取消确定原因，后续调用不会覆盖它。父子关系还要再看哪个 Context 先取消：父级先取消时，子级继承父级原因；子级先取消时，子级可以独立保留自己的原因。

参考资料：https://pkg.go.dev/context、https://go.dev/src/context/context.go、https://go.dev/doc/go1.20。如果只是需要一个结束信号，普通 WithCancel 足够；如果需要把“为什么结束”带到下游，就让创建取消 Context 的一方明确写入 cause，并让读取方同时保留 Err 的通用语义。