Go context.Cause 返回错误时怎么区分原因

在带超时、级联取消和并发任务的 Go 服务里，context.Cause(ctx) 返回一个 error 后，最容易犯的错是直接比较错误字符串。更稳妥的做法是把“状态”和“原因”分开：先用 ctx.Err() 判断是不是取消或超时，再用 errors.Is、errors.As 判断 cause 的具体类型。

官方文档：https://pkg.go.dev/context

一句话判断：ctx.Err() 适合回答“Context 现在处于什么标准状态”，context.Cause(ctx) 适合回答“它为什么被取消”。如果没有设置自定义 cause，后者会回退到前者。

先把“状态”和“原因”拆成两条信息

ctx.Err() 的结果通常只有两个标准值：context.Canceled 表示取消，context.DeadlineExceeded 表示截止时间或超时已经到达。它适合做流程分支，例如决定是否重试、是否返回超时响应。

context.Cause(ctx) 则可以携带更具体的错误。例如一个批处理任务被上层策略终止，状态仍然是 canceled，但原因可能是“租户配额已用尽”或“发布任务被替换”。这两个字段要同时保留，才能避免把业务原因误当成网络错误。

package main

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

func classify(ctx context.Context) string {
	// 先判断标准状态，避免把超时和主动取消混成一种结果。
	if errors.Is(ctx.Err(), context.DeadlineExceeded) {
		return "timeout"
	}
	if errors.Is(ctx.Err(), context.Canceled) {
		return "canceled"
	}
	// 没有取消时，Cause 也不应该被当成业务错误读取。
	return "active"
}

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel() // 释放派生 Context 的引用，保持调用方可复用。
	fmt.Println(classify(ctx))
}

主动取消时用 WithCancelCause 记录业务原因

如果调用方只是调用普通的 cancel()，下游只能看到 context.Canceled。需要携带原因时，创建 Context 的地方应改用 context.WithCancelCause，并把原因交给返回的 CancelCauseFunc。原因应该是稳定的错误值，而不是只适合日志阅读的拼接字符串。

package main

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

var ErrQuotaExhausted = errors.New("tenant quota exhausted")

func runJob(ctx context.Context) error {
	// 任务函数返回标准状态，调用方再从 Cause 读取更细的业务原因。
	if err := ctx.Err(); err != nil {
		return err
	}
	return nil
}

func main() {
	ctx, cancel := context.WithCancelCause(context.Background())
	// 取消动作携带可比较的 sentinel error，而不是依赖错误文本。
	cancel(ErrQuotaExhausted)

	err := runJob(ctx)
	fmt.Println(errors.Is(err, context.Canceled))
	fmt.Println(errors.Is(context.Cause(ctx), ErrQuotaExhausted))
}

这里的两个判断解决的是不同问题：runJob 返回的 ctx.Err() 告诉上层“任务被取消了”，context.Cause(ctx) 才能告诉上层“是配额策略触发了取消”。如果下游函数需要把 cause 直接返回，也应先确认调用方是否区分这两类信息，避免把业务错误包装成看似普通的网络失败。

超时时用 WithTimeoutCause 区分到期原因

超时场景建议使用 WithTimeoutCause 或 WithDeadlineCause。当时间到达时，Context 的标准状态仍然是 context.DeadlineExceeded，而 context.Cause(ctx) 可以提供“数据库查询超时”“下游报价超时”这类稳定分类。

package main

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

var ErrPricingTimeout = errors.New("pricing service timed out")

func main() {
	ctx, stop := context.WithTimeoutCause(context.Background(), 100*time.Millisecond, ErrPricingTimeout)
	defer stop() // 无论是否超时都释放计时器和派生 Context。

	

注意 WithTimeoutCause 返回的 CancelFunc 只负责提前结束并清理资源，不会把提前取消改写成设置好的超时 cause。这样可以区分“确实等到截止时间”和“调用方主动停止等待”两条路径。

沿父子 Context 判断 cause 从哪里传下来

Context 是一条取消传播链。父级取消时，子级也会收到取消；但排查时不能只看当前函数创建的 Context。要问三个问题：当前节点是否主动取消、父节点是否先取消、子节点是否已经记录了自己的 cause。

工程上可以遵循一个简单顺序：先在产生取消动作的边界记录原因，再在消费边界读取 context.Cause(ctx)。不要在每个下游函数里重新包装一个同名字符串，否则同一条传播链会出现多个无法比较的错误。

package main

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

var (
	ErrDeployReplaced = errors.New("deployment replaced")
	ErrWorkerStopped  = errors.New("worker stopped")
)

func main() {
	parent, cancelParent := context.WithCancelCause(context.Background())
	child, cancelChild := context.WithCancelCause(parent)

	// 子节点先取消时，先记录的子节点 cause 仍是当前节点的原因。
	cancelChild(ErrWorkerStopped)
	cancelParent(ErrDeployReplaced)

	fmt.Println(errors.Is(context.Cause(child), ErrWorkerStopped))
	// 清理两个 CancelCauseFunc，避免把它们保留到更长生命周期。
	cancelChild(nil)
	cancelParent(nil)
}

这类代码的关键不是记住所有 API，而是保证取消发生的边界唯一、可追踪。若一个子任务有自己的业务终止条件，就由它写入自己的 cause；若只是响应上游取消，就读取传播下来的 cause，不要覆盖。

用 errors.Is 和 errors.As 做稳定分类

字符串比较会受到包装、文案和多语言影响。固定的原因使用 sentinel error，带字段的原因使用自定义类型，再用 errors.Is 或 errors.As 做判断。记录日志时可以同时写入标准状态、cause 类型和任务标识，排查时就能分辨“取消了”与“为什么取消”。

package main

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

type RetryBudgetError struct {
	Used int
	Max  int
}

func (e *RetryBudgetError) Error() string {
	return fmt.Sprintf("retry budget exhausted: %d/%d", e.Used, e.Max)
}

func report(ctx context.Context) {
	// ctx.Err() 做通用状态分组，Cause 做业务原因分组。
	state := ctx.Err()
	cause := context.Cause(ctx)
	if errors.Is(state, context.Canceled) {
		var budgetErr *RetryBudgetError
		if errors.As(cause, &budgetErr) {
			fmt.Printf("canceled: retry budget %d/%d\n", budgetErr.Used, budgetErr.Max)
			return
		}
	}
	fmt.Printf("state=%v cause=%v\n", state, cause)
}

我在项目里会保留的排查顺序

我通常把下面的顺序放在任务边界，而不是散落到每个 goroutine 中：

1. 先调用 ctx.Err()，确认任务是 active、canceled 还是 deadline exceeded。
2. 如果已经取消，再调用 context.Cause(ctx)，不要把 nil cause 当成异常。
3. 对固定原因使用 errors.Is，对带字段原因使用 errors.As。
4. 日志中同时记录状态、cause 的类型和业务对象 ID，不记录只靠字符串才能恢复的关键信息。
5. 检查取消发生顺序：子节点先取消时，不要假设父节点的 cause 会覆盖子节点。

最终可以用下面的速查表避免混淆：

几个容易混淆的问题

context.Cause 返回 nil 时是不是调用失败了？

不一定。Context 还没有结束时，cause 可以是 nil；这时应该先看 ctx.Err()。只有已经收到 Done()，才进入取消原因的分类流程。

能不能直接比较 err.Error()？

不建议。错误可能被包装，也可能来自不同层次。把可判断的语义放进 sentinel error 或自定义错误类型，再用标准的 errors.Is、errors.As。

普通 WithCancel 能不能读取自定义原因？

普通 WithCancel 只能得到标准取消原因。需要让下游知道业务终止原因时，在产生取消动作的边界使用 WithCancelCause。

把 ctx.Err() 当作状态，把 context.Cause(ctx) 当作原因，再围绕取消发生边界定义可比较的 error，基本就能稳定地区分 Go 并发任务中的主动取消、超时和父级传播。