WithCancelCause 取不到取消原因的处理方法

使用 context.WithCancelCause 后却取不到取消原因，最常见的原因不是 API 失效，而是读取时机、读取对象或写入方式不对。先记住这条判断：必须等 ctx.Done() 关闭，再对同一个派生上下文调用 context.Cause(ctx)；如果调用的是 cancel(nil)，原因会退化为 context.Canceled。官方文档入口：https://pkg.go.dev/context。

先判断原因写入和读取是不是同一个上下文

WithCancelCause 返回的是一个新的派生上下文和 CancelCauseFunc。原因写在这个派生上下文上，读取也应围绕它展开。若代码在调用 cancel 后立刻读取，通常不会有问题；但在异步代码里，读取发生在取消之前，就只能得到 nil。

排查时先把读取点放到 之后，并确认没有把 parent、另一个子上下文或已经返回的局部变量传给 Cause：

package main

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

func main() {
    parent := context.Background()
    ctx, cancel := context.WithCancelCause(parent)
    cause := errors.New("上游配置缺失")

    // 先写入一个非 nil 原因，再等待取消信号确认状态已传播。
    cancel(cause)
    

这个例子中第一行输出为 true，第二行是“上游配置缺失”。如果 Cause 仍是 nil，优先检查取消是否真的执行，以及读取的是否仍是这个 ctx。

检查 cancel 的参数：nil 不是业务原因

CancelCauseFunc 接收一个 error。传入非 nil 错误时，context.Cause(ctx) 返回该错误；传入 nil 时，取消仍然发生，但原因按标准库约定表现为 context.Canceled。因此下面两种写法的语义不同：

// 业务失败：下游可以用 errors.Is 或错误类型继续判断。
cancel(errors.New("读取租户配置失败"))

// 只有“主动取消”语义：不会留下具体业务根因。
cancel(nil)

还要注意，原因是一次性写入的。第一次取消完成后，后续再次调用 cancel 不会替换已有原因。不要把多个 goroutine 的错误分别 cancel 后，再期待最后一个错误出现在日志里；应在一个明确的协调点选出要保留的根因。

用 Err 和 Cause 分开表达状态与根因

日志和返回值可以同时保留两层信息：ctx.Err() 适合判断流程是否应该停止，context.Cause(ctx) 适合解释为什么停止。只打印 Err 会把“配额不足”“上游主动终止”和“超时”都压成同一个取消状态。

如果需要区分错误类型，使用 errors.Is 或 errors.As 检查 Cause；不要通过比较错误字符串来做分支。

取消原因会被谁先写入决定

父子上下文之间遵循“先取消者决定原因”的规则。父上下文先以原因 A 取消，子上下文最终也会沿着取消链读到 A；如果子上下文先以原因 B 取消，子读到 B，而父上下文后来仍可有自己的原因。重复 cancel、在父级已经结束后才给子级写原因，都是“看起来写了但读不到预期值”的来源。

超时需要解释性原因时，使用 context.WithTimeoutCause 或 WithDeadlineCause，并保留返回的 cancel 以释放定时器资源。主动取消、超时和上游取消最好在不同层级各自负责，避免多个组件抢写同一原因。

常见问题

为什么调用了 WithCancelCause，Cause 还是 nil？

通常是读取发生在取消之前，或者读取了尚未取消的另一个派生上下文。先等待 Done，再确认上下文变量和 cancel 配对。

cancel(nil) 后能不能得到自定义字符串？

不能。需要把自定义信息封装成非 nil 的 error 传入 cancel；否则只能得到通用的 context.Canceled。

为什么第二次 cancel 没有覆盖第一次原因？

取消原因只由第一次取消确定。多个 goroutine 需要协作时，应在协调层选择一个稳定的根因再调用一次 cancel。

实际排查可按“是否已取消、是否同一个 ctx、是否传入非 nil error、父级是否先取消”的顺序进行。这样既能保留 Err 的流程语义，也不会丢掉 Cause 的业务信息。