Go Context 取消原因：不只是 “context canceled“ 那么简单

🤔 先从一个生活场景说起

想象你在餐厅点餐：

你：我要一份牛排，5分钟内上菜
服务员：好的（记下5分钟deadline）

2分钟后...
厨房：🔥 牛排煎糊了！

这时候服务员跑来告诉你：

❌ 旧方式："抱歉，您的订单取消了"
✅ 新方式："抱歉，牛排煎糊了，给您换一份还是退款？"

区别在哪？ 前者你只知道"没了"，后者你知道"为什么没了"，才能决定下一步怎么做。

Go 的 context 取消机制，以前就类似第一种情况：你只知道 context canceled，但不知道是客户端断连、超时、还是服务端主动关闭。

🔍 痛点：生产环境的"盲盒调试"

func processOrder(ctx context.Context, orderID string) error {
   
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    if err := checkInventory(ctx, orderID); err != nil {
   
        return err  // ❌ 只返回 "context canceled"
    }
    // ... 其他步骤
}

当这个函数返回 context canceled 时，你可能面临：

没有原因 = 无法精准决策 = 运维靠猜 😅

✨ WithCancelCause：给取消加上"小作文"

Go 1.20 引入的 WithCancelCause，核心就一个变化：

// 旧：cancel() 不带参数
ctx, cancel := context.WithCancel(ctx)
cancel()  // 原因：context.Canceled（默认）

// 新：cancel(cause) 可以传原因
ctx, cancel := context.WithCancelCause(ctx)
cancel(fmt.Errorf("库存服务连接超时: %w", err))  // ✅ 带上具体原因

实战改造

func processOrder(ctx context.Context, orderID string) error {
   
    ctx, cancel := context.WithCancelCause(ctx)
    defer cancel(nil)  // ① 正常完成时的"默认原因"

    if err := checkInventory(ctx, orderID); err != nil {
   
        // ② 失败时记录具体原因，%w 保留原始错误链
        cancel(fmt.Errorf("订单[%s]库存检查失败: %w", orderID, err))
        return err
    }

    if err := chargePayment(ctx, orderID); err != nil {
   
        cancel(fmt.Errorf("订单[%s]支付失败: %w", orderID, err))
        return err
    }

    return shipOrder(ctx, orderID)
}

读取原因

//  anywhere in the call chain
if cause := context.Cause(ctx); cause != nil {
   
    log.Error("请求异常", 
        "category", ctx.Err(),      // context.Canceled（分类）
        "reason", cause,            // 订单[xxx]库存检查失败: connection refused（具体原因）
    )

    // 还能用 errors.As 解包原始错误
    var netErr *net.OpError
    if errors.As(cause, &netErr) {
   
        // 针对网络错误做特殊处理
    }
}

💡 设计哲学 #1：首因制胜
第一次调用 cancel(cause) 设置的原因会被保留，后续调用自动忽略。
这确保了最靠近故障点的代码能决定最终原因，符合"谁发现问题谁负责描述"的原则。

⚠️ WithTimeoutCause 的"隐形陷阱"

Go 1.21 增加了 WithTimeoutCause，看起来很美：

ctx, cancel := context.WithTimeoutCause(
    ctx,
    5*time.Second,
    fmt.Errorf("订单[%s]处理超时", orderID),
)
defer cancel()  // ❗ 注意：这里返回的是普通 CancelFunc，不是 CancelCauseFunc

问题出在哪？

根本原因：WithTimeoutCause 返回的 cancel 是普通 CancelFunc，调用时无法传参，内部实现会强制用 context.Canceled 覆盖你的自定义原因。

💡 设计哲学 #2：兼容性优先
Go 团队明知可以返回 CancelCauseFunc，但为了保持 WithTimeout/WithDeadline 系列 API 签名一致（返回 CancelFunc），选择了"牺牲部分灵活性换取接口统一"。
这是 Go 著名的 "compatibility promise" 的体现：不破坏现有代码，哪怕新 API 会因此有点"别扭"。

🛠️ 最佳实践：手动 Timer 模式（覆盖所有路径）

如果你需要所有路径都有明确原因，推荐手动组合：

func processOrder(ctx context.Context, orderID string) error {
   
    // ① 统一用 WithCancelCause 管理取消原因
    ctx, cancel := context.WithCancelCause(ctx)
    defer cancel(errors.New("订单处理正常完成"))  // 默认成功原因

    // ② 手动创建 timer，超时时也走 cancel(cause)
    timer := time.AfterFunc(5*time.Second, func() {
   
        cancel(fmt.Errorf("订单[%s]处理超时(5s)", orderID))
    })
    defer timer.Stop()  // 正常返回时停止 timer

    // ③ 业务逻辑中失败时设置具体原因
    if err := checkInventory(ctx, orderID); err != nil {
   
        cancel(fmt.Errorf("库存检查失败: %w", err))
        return err
    }
    // ... 其他步骤

    return nil
}

优势

✅ 所有路径（超时/失败/成功）都有明确原因
✅ 首因制胜原则自动生效，最具体的错误优先
✅ 代码意图清晰，不依赖 API 的"隐藏行为"

代价

⚠️ ctx.Err() 永远返回 context.Canceled（不是 DeadlineExceeded）
⚠️ ctx.Deadline() 返回零值（影响 gRPC 等框架的 deadline 透传）

🎯 进阶：既要原因，又要 DeadlineExceeded

如果下游代码依赖 errors.Is(err, context.DeadlineExceeded) 做分支判断，可以嵌套 context：

func processOrder(ctx context.Context, orderID string) error {
   
    // 外层：管理业务原因
    ctx, cancelCause := context.WithCancelCause(ctx)

    // 内层：管理超时 + 保留 DeadlineExceeded 语义
    ctx, cancelTimeout := context.WithTimeoutCause(
        ctx, 5*time.Second,
        fmt.Errorf("订单[%s]超时", orderID),
    )

    // ⚠️ 注意 defer 顺序：LIFO，cancelCause 先执行
    defer cancelTimeout()  // 后定义，先执行
    defer cancelCause(errors.New("订单处理完成"))  // 先定义，后执行

    // 业务逻辑...
}

执行流程

正常返回: 
  cancelCause("完成") → 外层取消 → 内层继承 → ctx.Err()=Canceled, Cause="完成"

超时触发:
  内层 timer 触发 → 内层取消(DeadlineExceeded + 自定义cause) → 
  ctx.Err()=DeadlineExceeded ✅, context.Cause()=自定义超时原因 ✅

业务失败:
  cancelCause(具体错误) → 外层取消 → 内层继承 → 
  ctx.Err()=Canceled, Cause=具体错误

💡 设计哲学 #3：组合优于修改
不修改现有 API 行为，而是通过"外层管原因 + 内层管超时"的组合方式，同时满足多种需求。
这是 Go 典型的 "orthogonal design"（正交设计）：每个组件职责单一，通过组合解决复杂场景。

🧭 设计哲学总结

🚀 实战：HTTP 中间件集成

// middleware/cause_logger.go
func WithCauseLogging(next http.Handler) http.Handler {
   
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
   
        ctx, cancel := context.WithCancelCause(r.Context())
        defer cancel(errors.New("request_completed"))  // 默认成功原因

        // 把增强后的 context 传给下游
        next.ServeHTTP(w, r.WithContext(ctx))

        // 请求结束后记录原因（仅当确实被取消时）
        if err := ctx.Err(); err != nil {
   
            slog.Error("请求异常终止",
                "method", r.Method,
                "path", r.URL.Path,
                "category", err,                    // Canceled/DeadlineExceeded
                "reason", context.Cause(ctx),       // 具体业务原因
                "remote_addr", r.RemoteAddr,
            )
        }
    })
}

下游 handler 任意位置都可以：

func handlePayment(w http.ResponseWriter, r *http.Request) {
   
    // ...
    if paymentFailed {
   
        // 直接设置原因，中间件会自动记录
        if cancel, ok := context.CauseFunc(r.Context()); ok {
   
            cancel(fmt.Errorf("支付网关超时: %w", gatewayErr))
        }
        http.Error(w, "payment failed", http.StatusBadGateway)
        return
    }
}