Go context.WithCancelCause 怎么把超时原因传到最外层日志

线上请求超时后，日志里如果只有 context deadline exceeded，排查者还得回头猜：是上游主动放弃、下游查询太慢，还是某个业务条件提前终止？Go 1.20 引入的 context.WithCancelCause 可以把这次取消的具体原因沿着 Context 链带到最外层，日志因此能保留真正的故障边界。

想把 `context.WithCancelCause` 的超时原因透传到最外层日志，不用逐层手动透传错误，顺着取消信号的传递链路就能拿到根因，最后在入口层统一打印就可以覆盖全链路场景。

直接在最外层请求拦截/任务入口的 defer 逻辑里调用 `context.Cause(ctx)` 提取错误值，判断错误类型后直接输出到日志，就能拿到最内层调用 `cancel(err)` 时传入的自定义超时原因，不需要每层子协程单独打日志。

为什么 context.Err() 还不够定位超时

Context 有两个常被混用的观察点。Err() 返回 context.Canceled 或 context.DeadlineExceeded，很适合让业务快速决定“停止等待”；但它只表达取消类别，不表达是谁、在哪个环节、因为什么取消。

例如订单服务调用库存服务时，上游用户关闭页面和库存查询超过 800 毫秒，最终都可能在边界看到 context canceled。如果把具体原因在取消发生处写进 Context，日志就不必靠时间线猜测。

观察方式	能回答什么	不能回答什么
ctx.Err()	是否已取消、是否因截止时间结束	具体业务原因和触发位置
context.Cause(ctx)	取消链上记录的具体 error	没有调用取消函数时的释放问题

从取消发生处记录 cause

取消信号来源指的是超时触发、手动终止、下游报错这三类场景，所有要透传的自定义原因都要在这里作为参数传给 `cancel` 函数，不能用默认的空参数版本。

最小写法是用 WithCancelCause 替换 WithCancel。返回的函数接受一个 error；传入 nil 表示普通取消，传入具体错误则会被 Cause 读取。

package main

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

var errUpstreamTimeout = errors.New("inventory query exceeded 800ms")

func main() {
    ctx, cancel := context.WithCancelCause(context.Background())
    defer cancel(nil)

    cancel(errUpstreamTimeout)

    fmt.Println(ctx.Err())
    fmt.Println(context.Cause(ctx))
}

运行结果中，第一行仍是通用的取消状态，第二行才是业务诊断信息。这里的 defer cancel(nil) 是清理兜底；如果前面已经写入具体 cause，后面的 nil 不会把它覆盖掉。

原因记录的核心逻辑是 `WithCancelCause` 返回的 cancel 函数接收 error 类型入参，你触发取消的时候把具体的超时原因、错误标识塞进去，Go 标准库会自动把这个 error 绑定到 context 实例上。

父子 Context 如何把原因带到日志边界

派生子 Context 后，子级可以读取父级的取消原因。实际服务里可以让调用链最靠近故障的一层负责记录原因，HTTP、RPC 或任务入口只做统一日志输出。

func handle(ctx context.Context) error {
    child, cancel := context.WithCancelCause(ctx)
    defer cancel(nil)

    if err := queryInventory(child); err != nil {
        cancel(fmt.Errorf("inventory stage: %w", err))
    }
    return context.Cause(child)
}

func logBoundary(ctx context.Context) {
    if err := ctx.Err(); err != nil {
        fmt.Printf("request canceled: state=%v cause=%v\n", err, context.Cause(ctx))
    }
}

父子传播的过程不需要额外写转发逻辑，子 context 天生继承父 context 的取消信号，不管链路嵌套多少层子调用，最外层的根 ctx 都能通过 `context.Cause` 拿到最初传入的错误原因。

代码里的关键核对点有两个：业务函数返回前必须让取消函数真正执行；边界日志要调用 Cause，不能只把 Err 当成最终错误。若只是把 error 作为普通返回值向上层传递，另一个并发分支仍然无法从共享 Context 看到这次取消缘由。

超时、主动取消和业务失败要分开

日志落点放在 HTTP 中间件、任务调度入口、协程池入口这类统一收口的位置就可以，不用散落在各个业务函数里，只需要在 ctx 判定到 Done 通道关闭后，立刻取 Cause 打印日志即可。

如果原因本身是截止时间到期，WithTimeout 或 WithDeadline 已经能让 Err() 返回 context deadline exceeded。这时需要的是在日志中补充阶段名、目标服务和耗时，而不是把每个超时都包装成自定义错误。

主动取消更适合使用明确的业务错误，例如 errClientClosed、errCircuitOpen。错误要稳定，日志和指标才能聚合；不要把订单号、用户输入等高基数内容直接拼进错误文本，可以放到结构化字段里。

• 用户断开：记录 context.Canceled，并补充请求已离开的信息。
• 截止时间结束：记录 context.DeadlineExceeded，补充阶段和耗时。
• 业务主动终止：用固定错误值或可比较的错误类型，补充低基数原因码。

常见问题

context.Cause(ctx) 什么时候会返回 nil？

误区清理要避开几个常见问题：不要混用 `context.WithCancel` 和 `WithCancelCause`，前者没法拿到自定义原因；不要在子协程里覆盖父 ctx 的 cancel 方法，会打断传递链路；不要把普通业务错误直接塞给 cancel 之后还继续执行业务逻辑，取消信号触发后要尽快终止协程运行。

Context 还没有取消时会返回 nil。先判断 ctx.Err()，再读取 cause，日志语义更清楚。

子 Context 可以覆盖父 Context 的 cause 吗？

子 Context 自己先取消时可以拥有自己的原因；如果父 Context 先取消，子级通常观察到父级已经确定的取消原因。不要在每一层随意改写同一个故障。

只用 WithTimeout 还需要调用 cancel 吗？

需要。无论是否提前超时，都应在创建处用 defer cancel() 释放关联资源；不要等父 Context 自然结束。

Cause 能替代函数返回值吗？

不能。函数的业务失败仍应通过返回值表达；Cause 解决的是跨并发分支传播取消原因和统一观测的问题。

最后检查日志是否真的可诊断

上线前可以用一次人为取消和一次超时各跑一遍测试：确认 Err() 的类别正确，Cause() 没有丢失，最外层日志能看到阶段名，并且所有取消函数都覆盖了提前返回路径。这样改动才真正从“知道请求停了”推进到“知道请求为什么停”。