Go context.WithCancelCause 怎么用：让中断原因能被日志和调用方看见

订单页偶发提前结束时，日志里往往只留下 context canceled。这句提示没错，却回答不了“是谁停掉了这次调用”。库存端主动拒绝、灰度开关撤回和用户关闭页面，后续处理完全不同。context.WithCancelCause 能让取消信号继续传递，同时把真正的中断原因留给日志和调用方。

从一条看似超时的订单请求开始

有一次订单列表在 180ms 左右结束，网关标成取消，应用日志也只写了 context canceled。开始大家以为是浏览器中断；把下游日志按 trace ID 对齐后才发现，库存查询连续触发了本地熔断规则。

如果整条链路只看 ctx.Err()，这两种情况都会被归成“请求取消”。告警聚合失去区分度，排查又得翻多份日志。这里不必给每个函数塞一套自定义字段，先让原因沿着 Context 走到真正需要解释的边界。

结束信号和结束原因不是一回事

WithCancelCause 与 WithCancel 一样会返回派生 Context 和取消函数；区别是取消函数接收一个错误。调用 context.Cause 可以取回这个错误。若传入 nil，原因会是 context.Canceled。

分工可以很明确：ctx.Err() 让 select、重试循环和资源收尾尽快停下；context.Cause(ctx) 在日志、指标和错误映射处解释“为什么停”。Context 还未结束时，Cause 会返回 nil，不要拿它代替结束判断。

在业务边界补上可追查的原因

购物车读取失败后，把“库存暂不可用”作为取消原因带到上层；调用方再按自身协议决定如何响应。实际项目里，fetchCart 可能是 RPC、数据库或缓存调用，边界处理方式相同。

var ErrInventoryBusy = errors.New("inventory temporarily unavailable")

func loadCart(ctx context.Context, cartID string) error {
	ctx, cancel := context.WithCancelCause(ctx)
	defer cancel(nil)

	if err := fetchCart(ctx, cartID); err != nil {
		cause := fmt.Errorf("load cart %q: %w", cartID, ErrInventoryBusy)
		cancel(cause)
		return context.Cause(ctx)
	}
	return nil
}

调用 cancel(cause) 后，ctx.Err() 仍是 context.Canceled；具体原因要通过 context.Cause(ctx) 获取。另一个边界也别漏：内部日志可以保留错误包装链，外部客户端不应该收到依赖地址、堆栈或临时状态。

父子 Context 谁先结束，谁决定这段链路

子 Context 并不总能写入自己的原因。父 Context 先结束，子 Context 会得到父级原因；子 Context 先结束，它会保留自己的原因，父级随后结束也无法覆盖它。这是并发排查里很值得写成测试的一条规则。

func TestChildCauseWinsWhenItHappensFirst(t *testing.T) {
	parent, cancelParent := context.WithCancelCause(context.Background())
	defer cancelParent(nil)

	child, cancelChild := context.WithCancelCause(parent)
	childCause := errors.New("cache warmup stopped")
	cancelChild(childCause)
	cancelParent(errors.New("gateway closed"))

	if !errors.Is(context.Cause(child), childCause) {
		t.Fatalf("child cause = %v", context.Cause(child))
	}
}

这段测试不替代真实链路验证，但能把“最先发生的取消不会被后续覆盖”固定在代码库里。并发请求出问题时，别只盯单条日志；取消时间、根请求 ID 和 Cause 放在一起，顺序才看得出来。

日志、指标和响应各留多少信息

原因可以传下去，不代表每一层都要原样吐出去。一个稳妥的边界是：原始原因进入结构化日志，有限分类进入指标标签，HTTP 响应只给稳定业务码。

指标标签尤其要克制。带动态 ID 的错误文本会拉高基数，监控反而变难用。可以在统一错误处理层用 errors.Is 把已知原因映射到固定名称，未知原因归到 other，原始信息仍由日志承接。

复查时别漏掉取消函数

记录原因不等于资源管理自动完成。派生 Context 用完仍应调用取消函数；即使某条路径看起来最终会等父 Context 收尾，也别把它当作默认依赖。提前返回和多层分支交错的地方最容易遗漏。

代码审查时可以顺手问三个问题：派生 Context 的拥有者是谁？每条提前返回是否都能走到取消？原因只用于内部观测，还是会穿过公开接口？这几件事清楚后，WithCancelCause 才不会变成另一层难追的错误包装。

相关问题

可以用 Context 的 value 传错误原因吗？

不建议。value 适合请求范围内跨 API 传递的数据，不适合作为可变控制信号。取消原因有专门的 WithCancelCause 和 Cause。

超时也能设置自定义原因吗？

可以考虑 WithTimeoutCause 或 WithDeadlineCause。它们能区分超时与普通取消，对外响应仍要保持稳定。

收到 ctx.Done() 后还要读 Cause 吗？

如果只是快速退出循环，检查 ctx.Err() 足够；需要写日志、分类指标或决定重试策略时，再读取 context.Cause(ctx)。

每个函数都要创建 WithCancelCause 吗？

不必。只在需要给局部调用链补充独立原因的边界创建；纯透传函数直接接收现有 Context 更清晰。

把原因留在该留的位置

WithCancelCause 不会让中断的请求自动恢复，也不会替你设计错误协议；它补上的是“原因丢失”这一段。把完整信息留给日志，把有限分类留给指标，把稳定结果留给调用方，下次再看到 context canceled 时，排查就不用从猜测开始。