Go context 子任务为什么会提前出现 deadline exceeded

我排查过一类很容易误判的超时：父请求明明还剩一段时间，子 goroutine 却很快返回 context deadline exceeded。原因通常不是 Go 把子任务的计时器算错了，而是子 Context 的有效截止点不能晚于父 Context；子任务写入的 2 秒、5 秒只是上限，父 Context 更早结束时它必须一起结束。

父 Context 的 deadline 为什么会压过子任务 timeout

context.WithDeadline 的规则是“截止时间不晚于父 Context”；WithTimeout 只是把相对时长换算成 time.Now().Add(timeout) 后再套用同一规则。因此，父请求 800 毫秒后到期，子任务即使写了 5 秒，也最多只能活到那一个父 deadline。

这也是“子任务提前超时”的第一检查点：不要只看创建子 Context 时传入的 timeout，要把两个绝对时间放在一起看。

沿调用链定位是哪一层先结束

我更愿意先加观测，再改参数。每一层派生 Context 后记录它是否有 deadline、还剩多久；收到错误时用 errors.Is 判断标准超时，不要只比较错误字符串。

package main

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

// logDeadline 只观察当前层预算，不修改 Context，也不把子任务误当成独立计时器。
func logDeadline(name string, ctx context.Context) {
    deadline, ok := ctx.Deadline()
    if !ok {
        fmt.Printf("%s deadline=none\n", name)
        return
    }
    fmt.Printf("%s deadline=%s remaining=%s\n", name, deadline.Format(time.RFC3339Nano), time.Until(deadline).Round(time.Millisecond))
}

func main() {
    parent, stopParent := context.WithTimeout(context.Background(), 800*time.Millisecond)
    defer stopParent() // 无论成功或失败都释放父层计时器。

    child, stopChild := context.WithTimeout(parent, 5*time.Second)
    defer stopChild() // 子任务结束后及时解除父子引用和计时器。

    logDeadline("parent", parent)
    logDeadline("child", child)

    

这里的关键不是输出中的具体毫秒数，而是 child 的 deadline 不会落在 5 秒之后。若父 Context 在更早之前已经被取消，子 Context 的 Err 也可能是 context canceled，所以要把错误和父层日志一起看。

按剩余预算创建子任务 Context

固定给每个子任务 5 秒，是最常见的误导写法。更稳妥的办法是先读取父 deadline，再减去当前时间和收尾余量。下面的例子保留 100 毫秒给结果汇总、日志和资源关闭；如果剩余时间不足，就不再启动新的子任务。

package main

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

var errBudgetTooSmall = errors.New("child budget is too small")

// childContextFromRemaining 把父层绝对 deadline 转成子任务可用预算。
func childContextFromRemaining(parent context.Context, reserve time.Duration) (context.Context, context.CancelFunc, error) {
    deadline, ok := parent.Deadline()
    if !ok {
        // 没有父 deadline 时才使用一个明确的本地上限，避免无限等待。
        return context.WithTimeoutCause(parent, 2*time.Second, errBudgetTooSmall), func() {}, nil
    }

    remaining := time.Until(deadline) - reserve
    if remaining 

无 deadline 的父 Context 需要单独制定策略，不能悄悄把它当成“永不超时”。示例里的 2 秒只是业务上限，实际项目应按外部依赖和接口契约调整。

用 Cause 区分 deadline、上游取消和主动停止

ctx.Err() 适合做稳定分支判断：超时是 context.DeadlineExceeded，普通取消是 context.Canceled。Go 还提供 WithTimeoutCause 和 context.Cause，可以把“库存服务预算耗尽”“请求已断开”这类诊断原因记录下来，同时保留标准的 Err。

如果日志显示子层还有预算却收到 context canceled，优先查调用方是否执行了 cancel、HTTP 请求是否断开，或某个并行分支是否主动结束了共享父 Context。不要只把 timeout 调大；那可能掩盖真正的上游生命周期问题。

常见问题

子 Context 能不能覆盖父 Context 的 deadline？

不能。派生 Context 的 deadline 只能更早或保持不变，不能把父层已经结束的预算延长。

为什么每层都写 1 秒，实际总时间却不到 3 秒？

因为这些 1 秒是嵌套上限，不是串联预算；父层一旦先结束，所有子层都会收到取消。

什么时候应该使用 WithDeadline 而不是 WithTimeout？

跨多个函数或服务传递同一个业务截止点时，用 WithDeadline 更容易保持统一；只限制当前局部操作时，WithTimeout 更直观。