Go 怎样读取取消上下文的根因

在分层 Go 服务里，ctx.Err() 和 context.Cause(ctx) 解决的不是同一个问题：前者告诉调用方“上下文以什么标准状态结束”，后者回答“最先触发这次取消的具体错误是什么”。想同时获得稳定的分支判断和可追踪的根因，应把两者一起记录，而不是用一个错误字段替代另一个。

记住一个实用规则：用 Err() 判断是否取消或超时，用 Cause() 解释为什么取消。只有通过带 cause 的构造函数记录过原因，Cause() 才能提供比 Err() 更具体的信息。

为什么只看 Err 不够定位问题

一个请求通常会经过网关、业务服务和下游客户端。任何一层都可能因为用户离开、上游超时、依赖失败或服务主动降级而结束工作。如果所有层最后只输出 context canceled，调用链能知道任务停止了，却很难知道停止的起点。

Err() 的价值在于稳定。它只返回 context.Canceled、context.DeadlineExceeded 或 nil，适合用于 errors.Is、重试判断和响应分类。它不会把每个业务错误塞进公共状态里，这正是它适合做控制流判断的原因。

根因则属于另一层信息。Go 1.20 引入了 WithCancelCause 和 Cause，让主动取消可以携带一个错误；后续的取消原因 API 也覆盖了带截止时间的场景。这样可以让日志、链路事件或指标标签继续保留真实起点，同时让上层仍按标准状态工作。

主动取消时用 WithCancelCause 记录根因

如果取消动作来自业务判断，例如发现上游返回不可接受的数据，可以用 context.WithCancelCause 创建子上下文。返回的取消函数接收一个 error，这个错误会成为该上下文及其派生上下文可读取的根因。

package main

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

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

    // 业务层发现下游数据不可用时，写入真正触发取消的错误。
    cause := errors.New("下游配置中心返回空版本")
    cancel(cause)

    // Err 用于稳定的控制流判断，Cause 用于日志和链路定位。
    fmt.Println(errors.Is(ctx.Err(), context.Canceled))
    fmt.Println(ctx.Err())
    fmt.Println(context.Cause(ctx))
}

这段代码的三个输出关注点不同：第一行可以安全地用于判断是否属于主动取消，第二行是标准化状态，第三行才是业务根因。调用方不应该把第三行的文本直接当作协议错误码，因为它可能来自底层组件或业务包装。

如果传给取消函数的是 nil，上下文仍然会被取消，但原因会退回到标准的 context.Canceled。因此，只有在确实有可解释错误时才传入自定义原因；没有原因时不要为了“填字段”构造无意义的字符串。

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

取消原因不是每次调用 cancel 都会覆盖。一个 Context 或它的父级第一次完成取消时，原因就被确定。父级先取消时，所有子级通常会看到父级的原因；如果子级先取消，子级可以保留自己的原因，之后父级再取消也不会改写已经结束的子级。

package main

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

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

    // 让子 Context 先结束，子任务保留自己的失败原因。
    cancelChild(errors.New("子任务读取缓存失败"))
    // 父 Context 随后结束，但不会覆盖已经确定的子级原因。
    cancelParent(errors.New("请求被上游撤回"))

    fmt.Println(context.Cause(child))
    fmt.Println(context.Cause(parent))
}

不要把“父子 Context 最后应该只有一个统一错误”当成默认目标。父级原因适合描述请求级终止，子级原因适合描述局部任务失败。日志采集时可以同时打印两者；如果要向调用方返回单一错误，则应在业务边界明确选择优先级，而不是依赖字符串比较。

超时场景要区分自动原因与手动清理

普通的 WithTimeout 只能让 Err() 在超时后返回 context.DeadlineExceeded。如果服务需要把“库存服务超时”“配置中心超时”这样的边界写入根因，可以使用 WithTimeoutCause。

package main

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

func main() {
    timeoutCause := errors.New("库存服务在请求预算内未响应")
    ctx, cancel := context.WithTimeoutCause(
        context.Background(),
        50*time.Millisecond,
        timeoutCause,
    )
    defer cancel() // 无论是否已超时，都释放定时器等关联资源。

    

这里的语义很容易被误读：自动到达截止时间时，Cause(ctx) 可以返回预先给定的业务原因；但返回的普通 CancelFunc 只负责取消和资源清理，不负责在手动调用时写入这个原因。若手动路径也需要携带动态错误，应改用 WithCancelCause，或在上层单独记录主动终止原因。

在服务层把状态、根因和用户响应分开

在实际服务里，我更倾向于在边界函数中同时取出两个值，再分别用于不同通道：Err() 进入控制流，Cause() 进入结构化日志或链路事件，面向用户的响应则由当前接口契约决定。这样既不会把内部错误原文泄露给客户端，也不会因为统一错误码而丢失排查信息。

func handle(ctx context.Context) error {
    if err := doWork(ctx); err != nil {
        // 先判断取消状态，避免把客户端主动断开当成服务故障重试。
        if errors.Is(ctx.Err(), context.Canceled) {
            logCancellation(ctx.Err(), context.Cause(ctx))
            return err
        }

        // 截止时间属于可预期的控制流，根因用于区分具体依赖或业务阶段。
        if errors.Is(ctx.Err(), context.DeadlineExceeded) {
            logCancellation(ctx.Err(), context.Cause(ctx))
            return err
        }

        return err
    }
    return nil
}

这里假设 logCancellation 会把状态和根因作为两个字段写入日志，而不是拼成一条不可检索的字符串。根因可能为空、可能等于 Err()，也可能是更深层的包装错误，日志系统应保留错误链并做好脱敏。

一张表记住选择方式

常见疑问

只调用 context.Cause(ctx) 能拿到自定义错误吗？

不能保证。若上下文没有通过带 cause 的 API 记录具体错误，Cause 会返回与 Err 对应的标准错误；未取消时则返回 nil。

子 Context 会不会覆盖父 Context 的取消原因？

只对尚未取消的子级有效。子级先取消时可以拥有自己的原因；父级先取消时，父级的首次原因会沿传播链影响子级。

应该把 Cause 直接返回给 HTTP 客户端吗？

通常不应该。Cause 面向内部诊断，可能包含依赖名称、内部标识或敏感细节。对外响应应使用稳定的业务错误码，内部日志再记录经过脱敏的根因。

结语

把 Err() 看成“状态”，把 Cause() 看成“解释”，就不容易混淆 API 选择。普通取消和超时满足控制流需求，带 cause 的构造函数则为复杂调用链补上可观测性。真正上线时还要明确谁负责创建 cause、谁负责记录它，以及哪一层可以把内部根因转换成对外错误。

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