Go context.WithCancelCause 怎样把取消原因传给调用方完成一个可复用的最小示例

我在把一个后台 worker 接到 HTTP 请求或上层任务时，最常遇到的误区是：调用方只知道“上下文取消了”，却不知道到底是用户主动停止、依赖失败，还是内部校验没通过。context.WithCancelCause 的作用就是把这两个信息拆开传递：ctx.Err() 保留统一的取消状态，context.Cause(ctx) 返回真正导致取消的错误。

用 WithCancelCause 创建上下文，在 worker 失败时调用 cancel(err)；调用方等待 ctx.Done() 后同时读取 ctx.Err() 和 context.Cause(ctx)，就能既判断控制状态，又保留业务原因。

这个 API 自 Go 1.20 提供。它适合跨函数、跨 goroutine 传递取消原因，不负责替代错误通道、日志或重试策略。

用 WithCancelCause 建立调用方可读取的错误契约

最小可复用结构是由创建方持有 CancelCauseFunc，worker 只在确定需要终止时传入具体错误。调用方不要猜测 worker 做了什么，只读取上下文公开的两个结果。

var ErrQuotaExceeded = errors.New("quota exceeded")

func runWorker(ctx context.Context, cancel context.CancelCauseFunc) {
	// 这里代表一次不可继续的业务失败；把原始错误交给取消函数保存。
	err := doOneBatch(ctx)
	if err != nil {
		cancel(fmt.Errorf("worker stopped: %w", err))
		return
	}
	// 正常完成也要结束派生上下文，但 nil 不会制造额外业务原因。
	cancel(nil)
}

func waitWorker(parent context.Context) error {
	ctx, cancel := context.WithCancelCause(parent)
	// 调用方退出时兜底释放派生上下文，避免遗漏正常收尾。
	defer cancel(nil)

	go runWorker(ctx, cancel)
	

这里的契约很明确：Err 不会因为传入了自定义错误就变成自定义错误，它仍然是 context.Canceled；自定义错误只由 Cause 暴露。调用方因此可以用 errors.Is 判断业务类别，同时仍保留取消语义。

把正常退出、失败和外部取消分成三条路径

实际项目里，worker 可能同时面对三种结束原因：上游主动取消、当前操作失败、任务正常完成。建议让每条路径只负责自己的信号，避免把正常返回包装成“失败取消”。

func process(ctx context.Context, cancel context.CancelCauseFunc) error {
	if err := validateInput(); err != nil {
		// 输入不合法是业务原因，调用方可按错误类型决定是否重试。
		cancel(fmt.Errorf("validate input: %w", err))
		return err
	}

	select {
	case 

如果上层已经先取消，后续的 cancel(customErr) 不会覆盖第一次取消留下的原因。因此，worker 在观察到 ctx.Done() 后直接返回即可；真正的收尾由创建方的 defer cancel(nil) 兜底。

父子上下文的首次取消决定原因

取消原因不是一个可以反复改写的共享变量。父上下文先取消时，子上下文会继承父原因；如果子上下文先取消，它可以保留自己的原因，之后父上下文再取消也不会覆盖已经确定的子原因。这个边界适合把“请求级停止”和“子任务级失败”分开。

设计时可以按下面的判断清单落地：

• 调用方需要知道“是否取消”时读 ctx.Err()，需要知道“为什么取消”时读 context.Cause(ctx)。
• 业务失败传入非 nil error；主动清理或正常完成使用 cancel(nil)，其 cause 会落为 context.Canceled。
• 不要在多个 goroutine 中争抢并改写同一个原因；第一次取消生效后，后续调用只负责幂等收尾。
• 父上下文代表请求或作业总生命周期，子上下文代表一个可独立失败的阶段，二者不要共用无法区分的错误文本。

如果需要的是超时自动产生固定原因，可以考虑 WithTimeoutCause；如果只需要取消信号而不需要业务原因，普通的 WithCancel 更简单。

相关问题

• 调用 cancel(nil) 后 Cause 返回什么？ 返回 context.Canceled，而不是 nil；nil 表示没有额外的自定义原因。
• 为什么 ctx.Err() 不是传入的业务错误？ Err 保持统一的取消状态，业务错误由 Cause 提供，这样上层既能做状态判断，也能做错误分类。
• 子上下文先失败会修改父上下文的 Cause 吗？ 不会。子上下文保留自己的首次原因，父上下文仍按自己的首次取消原因计算。