Go context.WithCancelCause 怎么保留真正的取消原因

如果上层只读取 ctx.Err()，主动取消、超时和上游失败往往都会被压缩成一个笼统的状态。Go 1.20 提供的 context.WithCancelCause 可以在关闭取消信号的同时保存一个具体错误；调用方继续用 ctx.Err() 判断“是否已取消”，再用 context.Cause(ctx) 判断“为什么取消”。

保留真正取消原因的关键是：创建上下文时使用 WithCancelCause，触发取消时把原始错误传给返回的 CancelCauseFunc，读取时不要用 Err 代替 Cause。一个 Context 的首个取消事件会确定它和子 Context 的 cause。

WithCancelCause 与 Err、Cause 分别解决什么问题

WithCancelCause(parent) 返回一个派生 Context 和 CancelCauseFunc。后者接收一个 error，例如上游 RPC 失败、租约失效或业务任务主动终止。取消发生后，Done() 会关闭，Err() 仍然提供统一状态，而 Cause() 保留更具体的解释。

调用方怎样把真正的错误传进取消链

取消点通常位于拥有任务生命周期的函数中。把原始错误传给取消函数，再让下游只接收 Context，可以避免额外的全局变量或错误通道。

package worker

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

var errLeaseLost = errors.New("worker lease lost")

func runJob(parent context.Context) error {
    // cancel 负责关闭 Done，并记录任务停止的具体原因。
    ctx, cancel := context.WithCancelCause(parent)
    defer cancel(nil) // 正常返回时释放关联；已写入的 cause 不会被覆盖。

    if err := doWork(ctx); err != nil {
        cancel(err) // 把原始错误交给下游可读取的取消链。
        return err
    }
    return nil
}

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

示例中的 defer cancel(nil) 是资源释放习惯，不是把原因重置为 nil。取消原因只由第一次取消决定，因此发生 cancel(err) 后，后面的重复调用不会把它改掉。生产代码里还要让 doWork 真正把 ctx 传给数据库、HTTP 或队列客户端，否则上层保存了 cause，下游却不会及时停止。

父子 Context 的首个取消边界

cause 会沿着 Context 树向下传播，但“第一个取消事件”优先。如果父 Context 先因超时结束，子 Context 之后再收到业务错误，子 Context 看到的 cause 仍然是父级的取消原因。反过来，子 Context 先被业务错误取消，父级随后结束也不会覆盖子 Context 已记录的 cause。

因此不要把 Cause 当成“最后一次错误”。它表达的是取消链里最先发生、并被该 Context 观察到的取消原因。对超时场景，建议保留 errors.Is(context.Cause(ctx), context.DeadlineExceeded) 这类判断；对业务错误，则用稳定的哨兵错误或自定义类型承载可分支的信息。

常见误用与落地检查清单

• 仍用 WithCancel 创建 Context，却期望 Cause 自动知道业务错误：改为 WithCancelCause，并传入错误。
• 把 ctx.Err() 当作详细日志：它只说明取消类别，详细信息应从 Cause 获取。
• 多个 goroutine 同时取消并期待最后一个错误胜出：应设计谁拥有取消权，接受首个取消原因规则。
• 忽略 Go 版本：WithCancelCause 和 Cause 从 Go 1.20 加入，旧工具链需要继续使用兼容写法。

可以按这张清单检查：创建处是否保存了 CancelCauseFunc；所有退出路径是否调用取消函数；下游是否监听 Done；日志是否同时记录 Err 和 Cause；父级超时是否可能先于业务错误发生。

常见问题

调用 cancel(nil) 后 Cause 一定是 nil 吗？

不是。调用 cancel(nil) 会把 cause 视为 context.Canceled；取消前读取才是 nil。

Cause 和 Err 返回值可以互换吗？

不能。Err 适合做通用取消分支，Cause 用于保留第一次取消的具体错误。没有额外 cause 时，Cause 才会与 Err 相同。

子 Context 能覆盖父 Context 的 cause 吗？

只有子 Context 自己先发生取消时，它才会记录自己的 cause；如果父级先取消，父级原因会沿链路传给子级，后续子级原因不能覆盖它。

为什么保存了 cause，下游仍然没有停止？

cause 只记录取消原因，不会强制打断任意函数。下游必须监听 ctx.Done()，并把 Context 传给支持取消的 I/O 或数据库调用。