Go context.Cause 升级后行为变化怎么定位

Go 升级后发现 context.Cause(ctx) 和旧日志不一样，第一反应不应该是“标准库改坏了”。更常见的原因是代码从 WithCancel 换成了 WithCancelCause，或者父 Context、子 Context 的首次取消顺序发生了变化。先把 ctx.Err() 与 context.Cause(ctx) 分开记录，再沿着构造路径和取消时机回溯，通常能很快收敛到真正的差异。

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

Err() 回答“是否被取消以及属于取消还是超时”，Cause() 回答“第一次取消记录的具体错误是什么”。如果上下文从未取消，Cause() 返回 nil；如果没有设置具体原因，它会回退到 Err()。

先把升级前后的观察对象拆开

context.Cause 在 Go 1.20 引入，WithCancelCause 同时提供了带错误参数的取消函数。后续版本又增加了带超时原因的构造方式。升级本身可能只是让旧代码开始使用新的 API，真正改变结果的仍然是调用链里“谁先取消、用什么函数取消”。

先在同一个位置同时采集两个值，避免只看一条日志就下结论：

package main

import (
    "context"
    "fmt"
)

func printCancelState(ctx context.Context) {
    // Err 只描述取消状态；Cause 额外保留首次取消的具体错误。
    fmt.Printf("err=%v cause=%v\n", ctx.Err(), context.Cause(ctx))
}

如果旧版本只有 context canceled，升级后出现业务错误文本，不要直接认为语义冲突：很可能只是调用方从 WithCancel 切换成了 WithCancelCause。反过来，如果仍然使用普通 WithCancel，Cause 没有额外原因时本来就会与 Err 保持一致。

沿着构造函数确认原因是否有机会进入链路

排查的第二步是把创建 Context 的函数名记下来。WithCancel 返回的取消函数没有错误参数；WithCancelCause 返回的 CancelCauseFunc 才能把错误写入该 Context。只在调用点把变量名从 cancel 改成 cancelWithCause，并不会自动改变已经创建的 Context。

下面这个最小例子把“业务原因”和“取消状态”同时保留下来。代码中的输出是阅读时应关注的字段关系，文章没有把它当作本机执行结果：

package main

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

var errUserAbort = errors.New("用户主动取消")

func main() {
    parent := context.Background()
    ctx, cancel := context.WithCancelCause(parent)
    // defer 确保离开当前函数时释放 Context 关联资源。
    defer cancel(nil)

    // 业务分支把可比较的原因写入取消链路。
    cancel(errUserAbort)

    err := ctx.Err()
    cause := context.Cause(ctx)
    fmt.Println(err == context.Canceled)
    fmt.Println(errors.Is(cause, errUserAbort))
}

这里 ctx.Err() 仍然是 context canceled 这一类状态，而 Cause(ctx) 可以保留 errUserAbort。如果代码只记录 Err，升级后即使业务原因已经存在，日志仍然看不出来。

把“谁先取消”作为升级排查的核心交互

父子 Context 的行为不是最后一次调用决定的，而是第一次取消决定的。父 Context 先以 cause1 取消，子 Context 会继承这条原因；如果子 Context 先以 cause2 取消，子 Context 保留 cause2，之后父 Context 的原因不会覆盖它。

因此排查时不要只在请求结束处打印一次 Cause。应在创建点给父子对象标记角色，在每一个取消入口记录“对象、函数、错误、时间顺序”，再对照最终读取位置。日志字段保持固定比拼接一整段错误文本更容易比较升级前后差异。

可以把记录函数写成只读观察器，避免它改变取消状态：

func cancelSnapshot(label string, ctx context.Context) string {
    // 观察器不调用 cancel，只读取当前 Context 的状态和原因。
    return fmt.Sprintf("label=%s err=%v cause=%v", label, ctx.Err(), context.Cause(ctx))
}

func cancelWithReason(ctx context.Context, cancel context.CancelCauseFunc, reason error) error {
    if ctx == nil || cancel == nil {
        // nil 输入不进入取消链路，调用方得到明确的边界错误。
        return errors.New("context 或取消函数不能为空")
    }
    // 取消函数只记录第一次有效取消的原因，重复调用不会覆盖它。
    cancel(reason)
    return ctx.Err()
}

示例的重点不是增加一层封装，而是把排查证据集中在四个字段：构造函数、Context 角色、取消原因、取消顺序。字段齐全后，升级前后的差异才有机会被准确比较。

用错误身份判断变化，而不是比较展示文本

错误文本适合给人看，不适合承担全部分支判断。业务原因应使用包级哨兵错误、实现了 Is 的类型或其他稳定身份，再用 errors.Is 判断。这样即便错误被包装，排查仍然围绕同一个原因对象。

尤其不要写成 if err.Error() == "用户主动取消"。包装、翻译和实现调整都会让文本比较变脆；而 errors.Is 只表达你真正关心的错误身份。

性能和资源检查要单独处理

Cause 的返回值变化与性能问题不是同一个证据层。升级后看到 goroutine 数量上升，先检查每个 WithCancel、WithTimeout 或带原因的构造是否在所有控制流路径调用了取消函数；不要因为 Cause 输出更详细，就把资源问题归因给它。

标准库文档明确建议在操作完成后调用 CancelFunc，以释放 Context 关联资源。取消函数也不会等待业务 goroutine 自己退出，所以消费方仍要让工作循环监听 Done()，并用等待或其他同步方式确认退出。

性能记录建议至少区分三件事：Context 是否已取消、Cause 是否符合预期、相关 goroutine 是否完成退出。把这三项放在一条日志中虽然方便搜索，但判断时仍然要逐项解释，不能用 Cause 非空替代资源回收结论。

边界状态决定你看到的最终原因

以下几种情况最容易被误判成“升级后行为变化”。

• Context 尚未取消：ctx.Err() 与 context.Cause(ctx) 都是 nil。
• 使用普通 WithCancel：没有显式业务错误时，Cause 会回退到 Err。
• 显式传入 nil：它不会提供可识别的业务原因，后续应按取消状态处理。
• 父 Context 已先取消：子 Context 创建或取消时，可能直接继承父原因，子侧的后续记录不能覆盖首次原因。
• 超时构造不同：带原因的超时 API 与普通超时 API 的原因来源不同，不能只看函数名中的 Timeout 就假设结果相同。

最后可以按这张清单收口：先确认构造函数，再确认首次取消者；同时记录 Err 和 Cause；用错误身份而不是字符串判断；最后单独检查 goroutine 和取消函数的资源边界。只要四层证据一致，就能判断是 API 使用方式变化、调用顺序变化，还是确实需要进一步缩小到具体版本差异。

几个相关问题

为什么 Cause 返回的不是我最后一次传入的错误？

取消原因由第一次取消确定。Context 已经取消后，后续 CancelCauseFunc 调用不会覆盖原来的原因。

WithCancel 和 WithCancelCause 可以混用吗？

可以出现在同一棵父子树中，但每个 Context 的原因能力取决于自己的构造路径和祖先首次取消顺序，不能只看最外层变量名。

WithTimeoutCause 的取消函数会写入原因吗？

它为超时发生时预设原因，但返回的 CancelFunc 本身不设置该原因。主动提前取消时，应该按普通取消路径理解结果。

升级后日志文本变了，应该先回滚吗？

先按构造函数、首次取消、父子关系和错误身份四层对照。只有在最小复现排除调用顺序和 API 使用变化后，才值得继续检查具体版本差异。