Go context.Cause 结果不稳定怎么办

我在排查 Go 服务的取消日志时，最容易误判的一类现象就是：同一段代码有时打印业务错误，有时只打印 context canceled，于是感觉 context.Cause 结果不稳定。多数情况下，Cause 并没有随机变化，真正变化的是多个取消入口的先后顺序。

判断这类问题可以先记住一句话：context.Cause 返回的是该 context 或其父级发生的第一次取消原因；ctx.Err() 则更适合判断是普通取消还是超时。只要把取消入口、父子关系和观察时机拆开，问题通常就能定位。

官方资料：https://pkg.go.dev/context

为什么看起来像是 Cause 在变化

Cause 的值不是每次读取时重新计算的业务结论，而是取消状态建立时保存下来的结果。下面这个最小例子里，第二次取消不会把第一条错误覆盖掉：

package main

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

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

    first := errors.New("上游连接主动关闭")
    second := errors.New("本地超时")

    cancel(first)  // 中文说明：第一次取消写入 Cause。
    cancel(second) // 中文说明：同一个 context 已取消，这次不会覆盖 first。

    fmt.Println(ctx.Err())             // 中文说明：这里只看取消类别。
    fmt.Println(context.Cause(ctx))    // 中文说明：这里读取第一次取消保存的具体原因。
}

因此，如果日志里同一个请求有时出现 上游连接主动关闭，有时出现 本地超时，先不要怀疑 Cause 的实现。更应该检查这两个错误分别从哪里调用了同一个取消函数，以及它们是否运行在不同 goroutine 中。

先检查父子 context 的取消顺序

父子关系是第二个高频来源。子 context 不只是拥有一个独立的 Done 通道，它还会受到父 context 的取消传播影响。父级先取消时，子级会看到父级已经确定的结果；如果子级先被自己的 Cause 取消，后续父级取消通常不会改写子级已经保存的原因。

下面的代码只用于展示关系，不依赖具体业务。关键观察点是两个 context 的 Cause 不必相同：它们各自是否已经取消，以及哪个层级先完成取消，会决定最后看到的结果。

package main

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

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

    childReason := errors.New("子任务主动退出")
    parentReason := errors.New("请求整体结束")

    cancelChild(childReason)   // 中文说明：子级先取消，先保存自己的原因。
    cancelParent(parentReason) // 中文说明：父级随后取消，不覆盖已取消的子级。

    fmt.Println(context.Cause(child))  // 中文说明：预期关注子级最先记录的原因。
    fmt.Println(context.Cause(parent)) // 中文说明：父级记录自己的第一次取消原因。
}

排查线上代码时，可以沿着这条边界检查：谁创建了子 context，谁持有对应的 cancel 函数，父级是否被 HTTP 请求、服务关闭或上游错误提前取消。不要只在最底层打印 Cause，否则你只能看到结果，找不到取消源。

把 Err 和 Cause 分成两个观察维度

不少代码直接把 context.Cause(ctx) 当作所有分支的判断条件，这会让日志和业务处理混在一起。更稳妥的做法是：用 Err 判断取消类别，用 Cause 补充具体原因。

func classifyCancellation(ctx context.Context) string {
    if err := ctx.Err(); err != nil {
        // 中文说明：Err 先区分普通取消和截止时间到期，适合控制流程。
        if errors.Is(err, context.DeadlineExceeded) {
            return "deadline"
        }
        return "canceled"
    }

    // 中文说明：未取消时 Cause 为 nil，不要把它写成一个业务错误。
    return "running"
}

func logCancellation(ctx context.Context) {
    if err := ctx.Err(); err != nil {
        // 中文说明：同时记录类别和 Cause，方便区分超时、上游关闭等来源。
        fmt.Printf("cancel kind=%v cause=%v\n", err, context.Cause(ctx))
    }
}

这里的顺序很重要：先判断 Err 是否为 nil，再读取 Cause。官方文档定义了未取消的 context 其 Cause 为 nil；如果没有明确的 Cause，Cause(ctx) 也可能只是返回与 Err 相同的取消错误。

核对你使用的是哪一种超时 API

如果代码只调用 WithTimeout 或 WithDeadline，超时发生后通常只能得到 context deadline exceeded 这一类默认原因。Go 1.21 增加的 WithTimeoutCause 和 WithDeadlineCause 可以在超时到期时记录指定 Cause，但它们返回的普通 CancelFunc 不会因为手动调用而写入该超时 Cause。

func runWithDeadline(parent context.Context) error {
    timeoutReason := errors.New("下游报告窗口已关闭")

    ctx, cancel := context.WithTimeoutCause(parent, time.Second, timeoutReason)
    defer cancel() // 中文说明：释放计时器资源；手动 cancel 不代表 timeoutReason。

    if err := doWork(ctx); err != nil {
        // 中文说明：先返回业务错误，调用方再根据 ctx.Err/Cause 判断取消来源。
        return err
    }
    return nil
}

这段代码的核心是 API 语义，而不是“一定要让 Cause 等于业务错误”。如果任务在计时器到期前已经正常结束，Cause 仍可能是 nil；如果调用方提前手动取消，应该根据调用路径判断是主动结束还是超时结束。把普通 WithTimeout 和带 Cause 的版本混用，也是排查结果不一致时要先清理的差异。

多个 goroutine 同时取消时要收敛入口

真正容易制造随机观感的场景是：一个 goroutine 监控上游连接，另一个 goroutine 监控本地截止时间，第三个 goroutine 处理服务关闭，它们都拿到了同一个 CancelCauseFunc。代码没有违反 context 规则，但最终原因取决于哪一次调用先到达。

type cancelController struct {
    once   sync.Once
    cancel context.CancelCauseFunc
}

func (c *cancelController) request(reason error) {
    c.once.Do(func() {
        // 中文说明：集中记录第一次原因，避免多个来源重复写入和重复打印。
        c.cancel(reason)
    })
}

sync.Once 能让“只接受第一次原因”这条策略更明显，也方便把日志放在唯一入口。但它不会凭空创造业务优先级：如果产品规则要求“服务关闭优先于普通超时”，就不能把优先级交给 goroutine 调度，而要先收集各来源状态，再由一个明确的决策点选择原因。

最后用一组最小检查点复查

遇到 context.Cause 结果不稳定时，我通常按下面顺序查，不先改底层 API：

最终可以把问题收敛成一句话：context.Cause 不是一个会反复计算的随机值，而是取消传播过程中的一次性结果。只要固定取消入口、弄清父子先后，再用 Err 和 Cause 分开表达状态与原因，所谓“不稳定”通常就会变成一个可以解释的调度差异。

相关问题

• context.Cause 没有取消时为什么是 nil？因为 Cause 只在 context 已取消后才有非空原因，未取消状态应先处理为运行中。
• CancelCauseFunc 传 nil 会怎样？会把取消原因按普通取消处理，调用方不应把 nil 当成自定义业务错误。
• 子 context 能覆盖父 context 的 Cause 吗？只有子级先完成自己的取消时，子级才可能保留自己的原因；父级先取消后，传播结果会先确定。
• 为什么一定要 defer cancel？创建带超时或截止时间的 context 后及时调用 cancel，可以释放相关计时器和父子关系资源。