WithCancelCause 如何向调用链保留业务取消原因

调用链只返回 context.Canceled 时，上层知道“任务停了”，却不知道是用户主动取消、队列过载，还是下游策略要求终止。Go 的 WithCancelCause 解决的正是这层信息丢失：ctx.Err() 继续给出稳定的取消类别，context.Cause(ctx) 则保留第一次取消时传入的业务错误。

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

迁移时不要把业务错误塞进 ctx.Err()。让 Err 负责控制流，让 Cause 负责解释原因，调用链才既兼容又可观测。

先把 Err 和 Cause 分成两条信息

WithCancel 返回的取消函数没有参数，调用后通常只能得到 context.Canceled。改成 WithCancelCause 后，取消函数接收一个 error；非空错误会被记录，随后可由当前 Context 及其派生 Context 读取。

在调用链入口记录业务取消原因

入口负责定义原因，下游只消费 Context。下面的例子模拟一个导出任务：用户点停止时记录稳定的哨兵错误，处理函数仍然通过 Done 及时退出。

package main

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

var ErrUserStopped = errors.New("export stopped by user")

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

这里的两个判断分别输出 true。不要让 export 直接把原因替代成普通错误返回，否则同一条调用链上的其他函数会失去取消语义；更稳妥的约定是返回 ctx.Err()，在边界层读取 Cause。

父子 Context 的第一次取消决定原因

取消原因遵循“先发生者生效”。如果父 Context 先以 ErrOverloaded 取消，子 Context 之后传入的错误不会覆盖它；反过来，子 Context 先取消，则子节点保留自己的原因，父节点仍保留父节点的原因。这个差异在请求超时和用户主动停止同时存在时尤其重要。

var ErrOverloaded = errors.New("queue overloaded")

parent, stopParent := context.WithCancelCause(context.Background())
defer stopParent(nil) // 避免父节点关联长期存活。

child, stopChild := context.WithCancelCause(parent)
defer stopChild(nil) // 子节点独立收尾，不覆盖已经写入的原因。

stopChild(ErrUserStopped)
// context.Cause(child) 是 ErrUserStopped；后续 stopParent 不会改写 child。

因此，创建子 Context 的函数要明确谁拥有取消权。下游可以读取原因，但不应擅自再次取消共享的父 Context；否则一个局部策略可能把整条请求链提前终止。

迁移时的四项检查

如果旧代码只需要判断取消类别，可以暂时保留 ctx.Err()；当业务需要区分用户停止、资源超载和父请求中断时，再把构造函数换成 WithCancelCause，并在统一错误边界增加 context.Cause(ctx) 的记录。这样迁移范围小，也不会改变已有的 select 控制流。

常见问题

cancel(nil) 会不会保留一个自定义原因？

不会。首次取消时传入 nil，Cause 会表现为普通取消；如果已有原因，后续 cancel(nil) 也不能清空或覆盖它。

Cause 和 Err 是否总是返回同一个错误？

不一定。带原因取消时，Err 通常是 context.Canceled，Cause 才是业务错误；没有单独原因时，两者才可能相同。

超时也要使用 WithCancelCause 吗？

若只是判断超时，WithTimeout 已够用；若需要给超时附加固定解释，可评估 WithTimeoutCause，不要用人工 goroutine 竞争写原因。

实际迁移可以遵循一个简单顺序：先保留 ctx.Err() 的控制流，再用 WithCancelCause 记录原因，最后在调用链边界用 errors.Is(context.Cause(ctx), target) 做分类。这样既不破坏旧接口，也让一次取消真正能说明“为什么发生”。