Go context用取消原因区分失败来源的排查方法

排查 Go 服务里的“请求被取消”时，单看 ctx.Err() 往往只能得到 context canceled 或 context deadline exceeded，还不知道是谁触发了取消。更实用的做法是用 context.WithCancelCause 记录具体错误，再用 context.Cause(ctx) 读取它。这样既保留旧代码依赖的通用状态，又能把日志归因到客户端中止、上游失败或超时。

这套方法的边界很明确：Err 用来判断工作是否应该停止，Cause 用来解释停止原因；不要把 cause 当成新的控制信号，也不要在下游重新猜测上游发生了什么。

用WithCancelCause定义可区分的取消来源

先把可观测的失败来源定义成错误值。业务层调用 cancel 时传入原因，底层任务只接收一个普通的 context.Context，因此函数签名仍然保持标准 Go 风格。

package main

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

var errClientClosed = errors.New("client closed request")

func main() {
    ctx, cancel := context.WithCancelCause(context.Background())
    defer cancel(nil) // 兜底释放关联资源，已取消时不会覆盖首次原因

    cancel(errClientClosed) // 记录这次取消的业务来源

    fmt.Println(ctx.Err() == context.Canceled) // 保留兼容的通用状态
    fmt.Println(context.Cause(ctx) == errClientClosed) // 读取具体取消原因
}

官方 API 的关键点是：传入非空 error 后，ctx.Err() 仍是 context.Canceled，而 context.Cause(ctx) 返回传入的错误；传入 nil 时，cause 会落到通用的 context.Canceled。同时，取消函数仍应在函数结束时调用，避免派生 context 和定时器长期滞留。

沿调用链传递ctx并分别读取状态与原因

下游不需要知道 cancel 函数，只要在阻塞点监听 Done，返回时同时检查 Err 和 Cause。工程上建议把二者分工固定下来：Err 决定是否退出循环或中止 I/O，Cause 写入结构化日志、指标标签或排查字段。

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

不要只用 errors.Is(err, context.Canceled) 就结束归因，因为它无法回答“哪一个上游动作取消了请求”。推荐让边界层记录 state、cause 和请求标识，重试策略则根据具体 cause 白名单决定，而不是对所有取消都重试。

按父子取消先后判断真正的失败来源

cause 不是后来写入的备注，而是首次取消时锁定的结果。父 context 先取消，父子都会继承父的 cause；子 context 先取消，子可以保留自己的 cause，父 context 随后仍使用自己的原因。这个顺序正是排查“请求超时还是子任务失败”的关键。

func childFailure(parent context.Context) (context.Context, context.CancelCauseFunc) {
    child, cancel := context.WithCancelCause(parent)
    go func() {
        // 这里应在真实业务错误出现时传入原始错误，而不是统一写Canceled。
        cancel(errors.New("upstream profile service rejected request"))
    }()
    return child, cancel
}

如果父请求已经因为超时关闭，子任务再调用自己的 cancel 不会改写子 context 已继承的原因；反过来，子任务先失败时，子 context 的 cause 可以精确保留上游错误。日志里最好同时输出父、子两个 context 的 Err 和 Cause，不要只看最外层返回值。

为超时设置稳定cause并建立排查表

超时是最常见的取消来源。只需要通用超时状态时，WithTimeout 已经足够；要让超时日志带上业务边界，可以使用支持 cause 的超时构造函数，再把客户端主动取消和上游失败分别定义成独立错误。

func withBudget(parent context.Context) (context.Context, context.CancelFunc) {
    // cause只描述预算耗尽，不把具体下游名称硬编码进通用状态。
    return context.WithTimeoutCause(parent, 800*time.Millisecond,
        errors.New("profile dependency budget exhausted"))
}

上面的示例需要导入 time，并适用于提供 WithTimeoutCause 的 Go 版本；更老的版本可以继续使用 WithTimeout，在调用边界自行包装超时日志。排查时可按下面的对应关系行动：

常见问题

context.Cause(ctx) 可以替代 ctx.Err() 吗？

不能完全替代。Err 是标准 Context 契约中的停止状态，适合让调用方快速判断取消或超时；Cause 是更细的诊断信息，适合日志和策略判断。两者应一起保留。

多个 goroutine 同时调用 cancel 会怎样？

取消函数可以并发调用，但只有第一次取消会设置 cause，后续调用不会覆盖它。因此要让最接近原始失败的位置尽早传入真实错误，避免在最外层统一改写成模糊字符串。

落地时可以记住一个简短规则：用 Done 停止工作，用 Err 判断状态，用 Cause 解释来源；再结合父子 context 的取消顺序，日志通常就能从“请求被取消”推进到“哪一层、因为什么取消”。