Go 的 context.WithTimeout 为什么提前结束：父子截止时间与取消传播

服务端给下游调用留了 800 毫秒，代码里却只跑了不到 200 毫秒就收到 context deadline exceeded。这通常不是 WithTimeout 失灵，而是外层请求的父 Context 已经只剩很短时间：子 Context 的截止时间取父 deadline 和自身 timeout 中更早的那个。

context.WithTimeout(parent, 800*time.Millisecond) 不是重新获得 800 毫秒预算；如果 parent 还有 150 毫秒就到期，子 Context 也最多只能活 150 毫秒。

为什么子 Context 会比 timeout 参数更早结束

Context 的截止时间是一棵树上的约束。父 Context 如果已有更早的 deadline，WithTimeout 会继承这个更紧的边界，而不会把时间往后延。下面的代码故意让父 Context 只剩约 120 毫秒，再给子 Context 配 800 毫秒：

package main

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

func main() {
    parent, parentCancel := context.WithTimeout(context.Background(), 120*time.Millisecond)
    defer parentCancel()

    child, cancel := context.WithTimeout(parent, 800*time.Millisecond)
    defer cancel()

    parentDeadline, _ := parent.Deadline()
    childDeadline, _ := child.Deadline()
    fmt.Println("parent deadline:", parentDeadline)
    fmt.Println("child deadline:", childDeadline)

    

输出中的两个时间点不会相差 800 毫秒，子 deadline 会贴近父 deadline。排查线上问题时，先把这两个值打印到同一次调用链里，通常比盯着配置文件更快找到原因。

用 ctx.Done 区分谁先发出了取消信号

“提前结束”还可能是主动调用了 cancel，或者上游请求先结束。不要只根据耗时猜原因，让实际工作在等待点监听 ctx.Done，并在返回处检查 ctx.Err()：

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

如果返回的是 context.DeadlineExceeded，要继续沿调用链检查父 deadline；如果是 context.Canceled，重点查谁调用了 cancel 或谁关闭了上游请求。这里的状态不是业务错误码，不能简单改成“再加大 800 毫秒”来掩盖根因。

三个容易误判的边界

把每一层 timeout 相加

外层 1 秒、内层 800 毫秒，并不代表内层能独立获得 800 毫秒。deadline 是最早到期者生效，层层派生只会缩短可用时间。

成功返回就不需要 cancel

只要创建了带 deadline 的 Context，就应在同一作用域 defer cancel()。官方文档说明 cancel 会释放计时器等关联资源，也会解除父 Context 对子 Context 的引用。

只看 timeout，不记录 deadline

配置值表达的是“最多允许多久”，不等于本次调用真正拿到的剩余时间。诊断日志应同时记录父子 deadline、ctx.Err() 和调用阶段。

一套可复查的排查顺序

1. 在创建子 Context 前调用父 Context 的 Deadline()，确认是否已经接近到期。
2. 创建 WithTimeout 后再次调用子 Context 的 Deadline()，比较两个绝对时间点。
3. 在数据库、HTTP 或下游 RPC 的等待点监听 ctx.Done()，返回 ctx.Err()。
4. 沿调用链搜索提前执行的 cancel()，并保留每个派生 Context 的局部作用域。

这套顺序能把“父 deadline 太短”“主动取消”和“真正超时”分开。修复后再用一个比父 deadline 更晚的子 timeout 做回归，确认子 deadline 仍然不会越过父边界。

相关问题

WithTimeout 和 WithDeadline 应该怎么选？

调用方只关心相对时长时用 WithTimeout；多个服务需要共享一个绝对截止点时，用 WithDeadline 更直观。两者都受父 Context 更早 deadline 约束。

为什么 defer cancel 仍要保留？

因为业务可能在计时器到期前正常返回，defer cancel 能及时释放子 Context 相关资源，并让代码在异常返回路径上也保持一致。

最后记住这条判断

看到 context deadline exceeded 时，先问“父 Context 还剩多久”，再问“这一层配置了多久”。把父子 deadline、ctx.Done 和 cancel 放在同一条调用链里，提前结束通常就能被复现和解释。