Go 怎样保留超时上下文的取消原因

如果一个 Go 请求既有截止时间，又希望在日志里说明“为什么取消”，不要只依赖 ctx.Err()。更合适的做法是用 context.WithTimeoutCause 创建带超时原因的派生上下文，再用 context.Cause(ctx) 读取原因。这样可以把“状态是超时”和“业务上为什么设置这个超时”分开保存。

最小写法是：ctx, cancel := context.WithTimeoutCause(parent, timeout, cause)，工作函数结束后记得 defer cancel()；发生取消后，用 ctx.Err() 判断状态，用 context.Cause(ctx) 读取原因。

先分清 Err 和 Cause 的职责

ctx.Err() 适合做分支判断：常见结果是 context.DeadlineExceeded 或 context.Canceled。它告诉你上下文处于哪一种取消状态，但不会携带这次请求的业务解释。

context.Cause(ctx) 读取的是取消原因。使用 WithTimeoutCause 时，截止时间到达后它会返回创建上下文时绑定的那个 error。因此可以把错误码、依赖名称或操作阶段写进原因，但不要把用户输入、密钥等敏感信息直接拼进去。

用 WithTimeoutCause 写出最小配方

下面的配方把“库存服务查询超时”作为原因。代码只演示上下文语义，底层工作可以替换成数据库、HTTP 客户端或消息系统调用。

package main

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

var errInventoryTimeout = errors.New("库存服务查询超时")

func main() {
    parent := context.Background()

    // 截止时间和原因同时绑定到派生上下文，便于上层记录稳定语义。
    ctx, cancel := context.WithTimeoutCause(parent, 80*time.Millisecond, errInventoryTimeout)
    defer cancel() // 释放计时器和父子上下文关系，避免不必要的资源保留。

    err := loadInventory(ctx)
    if err != nil {
        // Err 判断取消状态，Cause 保留这一次取消对应的解释。
        fmt.Printf("state=%v cause=%v\n", ctx.Err(), context.Cause(ctx))
        return
    }

    fmt.Println("inventory loaded")
}

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

这里的关键不是把错误字符串打印出来，而是把职责拆开：loadInventory 只关心工作是否被取消，调用方再根据 Cause 决定日志字段、重试策略或响应码。这样底层函数不需要知道“库存服务”之外的业务分类。

把原因传到实际工作函数

工程代码里不要在每一层重新创建超时原因，否则日志很容易出现多个互相矛盾的版本。更稳妥的方式是由拥有截止时间的边界层创建上下文，把它继续传给下游。

func handleRequest(parent context.Context) error {
    // 由请求边界统一设置超时原因，下游复用同一个派生上下文。
    ctx, cancel := context.WithTimeoutCause(
        parent,
        300*time.Millisecond,
        errors.New("订单详情读取超时"),
    )
    defer cancel()

    if err := readOrder(ctx); err != nil {
        // 保留底层返回的业务错误；取消原因单独交给日志或监控字段。
        if errors.Is(ctx.Err(), context.DeadlineExceeded) {
            return fmt.Errorf("request canceled: %w", context.Cause(ctx))
        }
        return err
    }
    return nil
}

func readOrder(ctx context.Context) error {
    // 所有阻塞调用都必须监听 Done，否则超时只改变状态而不会停止工作。
    select {
    case 

需要注意，WithTimeoutCause 绑定的是“截止时间到达时使用的原因”。如果底层业务在超时前主动返回了自己的错误，调用方仍应优先保留这个业务错误，不要无条件改写成上下文原因。

主动取消时不要误报成超时

父上下文也可能先于截止时间被取消，例如客户端断开连接、上层任务停止或服务开始优雅退出。此时 ctx.Err() 通常是 context.Canceled，原因也会沿着父子上下文关系传播。

func runJob(parent context.Context) error {
    // 让父上下文负责请求生命周期，当前层只增加一个截止时间。
    ctx, cancel := context.WithTimeoutCause(parent, 2*time.Second, errors.New("后台作业超时"))
    defer cancel()

    select {
    case 

几个容易混淆的兼容边界

• 只需要状态时：继续使用 WithTimeout 即可；它的重点是截止时间，不额外绑定自定义原因。
• 需要主动传入原因时：考虑 WithCancelCause，由调用方在取消动作发生时传入错误。
• 要判断来源时：先比较 ctx.Err()，再读取 context.Cause(ctx)；不要只拿错误字符串做判断。
• 要释放资源时：派生上下文创建后通常立即 defer cancel()。即使最终是父上下文先取消，也应保留这个清理动作。
• 要兼容旧版本时：WithTimeoutCause 和 Cause 来自较新的 Go 标准库能力，项目应按实际最低 Go 版本决定是否采用；不能只因为本机编译器较新就忽略构建矩阵。

可直接复用的完整片段

package timeoutcause

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

var ErrDependencyTimeout = errors.New("依赖调用超时")

// DoDependencyCall 用统一的状态和原因返回值描述一次可取消调用。
func DoDependencyCall(parent context.Context) error {
    ctx, cancel := context.WithTimeoutCause(parent, 250*time.Millisecond, ErrDependencyTimeout)
    defer cancel() // 无论成功、失败还是父上下文取消，都释放当前派生上下文。

    select {
    case 

如果上层还要做重试，可以把 context.Cause 作为日志或指标的分类字段，而把返回错误交给调用链处理。这样既不会丢掉截止时间状态，也不会把不同来源的取消混成一个模糊的“请求失败”。

相关问题

WithTimeoutCause 的原因会自动出现在 ctx.Err() 里吗？
不会。ctx.Err() 仍然返回标准状态错误；自定义原因应通过 context.Cause(ctx) 读取。

调用 cancel 后一定会读取到自定义原因吗？
要看取消来源。如果是截止时间到达，读取到的是创建时绑定的原因；如果父上下文更早取消，原因可能来自父上下文。

底层函数必须返回 context.Cause(ctx) 吗？
不必。底层通常返回 ctx.Err()，由拥有上下文边界的上层统一记录 Cause，更容易保持错误处理一致。

参考入口：https://go.dev/doc/