你用了 context.WithTimeout，设了 5 秒，觉得稳了。

超时保护嘛，5 秒内搞不定就取消，资源不泄漏，完美。

但这几个行为你大概遇到过：gRPC 服务链路正常，HTTP 的下游服务像没收到超时一样跑了 30 秒，上游早就返回失败了，下游还在执行扣款。

不是 bug，是 context.WithTimeout 的传播规则在按设计工作。只是它的设计和你的直觉不一样。

不是你代码写错了，是你对 context.WithTimeout 的心智模型有偏差。大多数人对它的理解停留在"设一个超时时间，到期取消"这个层面。这没错，但太粗了，粗到在生产环境会掉进去。

过去大半年把踩过的坑和同事们遇到的问题归纳了一下，提炼出 5 个容易在压力下犯错的行为。每个配代码实测，核心逻辑可直接嵌入你的测试文件验证。即使你知道这些规则，在具体场景下仍然会中招。

1. WithTimeout 的计时从调用瞬间开始

你以为：设了 3 秒超时，下游操作就有 3 秒时间跑。

实际：计时从 context.WithTimeout() 被调用的那一刻开始。之后的所有等待，等 DNS 解析、等 TLS 握手，全部算在这 3 秒内。

这个坑在高并发场景下特别明显。你的服务调用一个第三方 API，高峰期 DNS 解析偶尔慢、TLS 握手偶尔卡。你给请求设了 500ms 超时，以为"半秒够了，接口很快"。但 DNS + TLS 握手花了 400ms，实际留给请求执行的只有 100ms。结果不是下游慢，是你的超时预算被握手阶段吃掉了。

来看代码：

ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()

fmt.Printf("WithTimeout 调用时刻: %s\n", time.Now().Format("15:04:05.000"))

// 模拟排队等待 2s（DNS 解析、TLS 握手...）
time.Sleep(2 * time.Second)

// 排队结束，终于轮到你了
deadline, _ := ctx.Deadline()
remaining := time.Until(deadline)
fmt.Printf("开始做事，剩余时间: %v\n", remaining.Round(time.Millisecond))
fmt.Printf("你以为有 3s，实际只剩 %v\n", remaining.Round(time.Millisecond))

// 尝试一个需要 2s 的操作
select {
case <-time.After(2 * time.Second):
    fmt.Println("操作完成 ✓")
case <-ctx.Done():
    fmt.Printf("操作被取消 ✗ (%v)\n", ctx.Err())
}

运行结果：

WithTimeout 调用时刻: 11:34:02.832
开始做事，剩余时间: 1s
你以为有 3s，实际只剩 1s
操作被取消 ✗ (context deadline exceeded)

3 秒的超时，排队花了 2 秒，真正做事只剩 1 秒。操作需要 2 秒，直接被取消。

为什么是这样？

context.WithTimeout(ctx, 3s) 的内部实现等价于：

context.WithDeadline(ctx, time.Now().Add(3*time.Second))

它记录的是一个绝对时间点，“从现在起 3 秒后的那个时刻”。这个时间点一旦确定就不会变，不管这 3 秒内你在干嘛（排队、等锁），到点就取消。

怎么办：

1. 如果操作前有不可控的等待（连接池排队是典型场景），把等待时间预估进 timeout 值。经验公式：timeout = 预期操作时间 + P99（99%的请求不超过这个时长）排队时间 + buffer
2. 或者更好的做法，把 WithTimeout 放在"真正开始做事"的位置。比如 pgxpool 支持获取连接后再绑定 context，go-redis 的 PoolTimeout 与命令 timeout 独立配置
3. 加一层监控：记录"从 WithTimeout 调用到真正执行操作"之间的耗时。如果这段时间的 P99 接近你的 timeout 值，说明连接池正在成为瓶颈，该扩容了

2. 子 context 设更长的 timeout 无效

你以为：父 context 3 秒，子 context 设 10 秒，子可以多跑一会儿。

实际：子 context 的 deadline 永远 ≤ 父 context 的 deadline。你设 10 秒、设 100 秒、设 1 小时，拿到的都是父的 3 秒。

这个误解在微服务中很常见。网关设了 3s 超时，业务服务觉得"我这个操作复杂，给自己 10s 吧"。没用，网关 3 秒一到，整条链路全部取消。

parentCtx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()

// 子 context 请求 10 秒
childCtx, childCancel := context.WithTimeout(parentCtx, 10*time.Second)
defer childCancel()

parentDeadline, _ := parentCtx.Deadline()
childDeadline, _ := childCtx.Deadline()

fmt.Printf("父 deadline: %s (3s后)\n", parentDeadline.Format("15:04:05.000"))
fmt.Printf("子 deadline: %s (你以为10s后)\n", childDeadline.Format("15:04:05.000"))
fmt.Printf("子 deadline == 父 deadline? %v\n", childDeadline.Equal(parentDeadline))

// 等子 context 被取消
start := time.Now()
<-childCtx.Done()
fmt.Printf("\n子 context 实际存活: %v\n", time.Since(start).Round(time.Millisecond))
fmt.Printf("取消原因: %v\n", childCtx.Err())

运行结果：

父 deadline: 11:34:15.964 (3s后)
子 deadline: 11:34:15.964 (你以为10s后)
子 deadline == 父 deadline? true

子 context 实际存活: 3.001s
取消原因: context deadline exceeded

请求了 10 秒，拿到的是 3 秒。deadline 完全一样。

源码逻辑：context.WithDeadline 内部会做这个比较：

// 简化版逻辑
if cur, ok := parent.Deadline(); ok && cur.Before(newDeadline) {
    // 父 deadline 更早，用父的
    return context.WithCancel(parent)
}
// 否则用新的 deadline

注意：WithCancel(parent) 返回的 context 通过 parent 链仍然继承父的 deadline，Deadline() 会返回父的时间点。只是不需要再设独立定时器了，因为父到期时整条链一起取消。

为什么这么设计？

从资源管理角度想：用户发了一个请求，网关给了 3 秒期限。3 秒后用户已经看到"请求超时"了，你的服务还在跑 10 秒，跑完了也没人要结果，纯粹浪费 CPU 和连接。

“最短者胜"的设计目的是防止资源泄漏：上游已经不要结果了，下游就该停。

正确姿势：

如果子任务确实需要比父活得更久（比如异步写审计日志、发送事件通知），应该显式脱离父 context 的取消链：

// Go 1.21+ 推荐方式
detachedCtx := context.WithoutCancel(parentCtx)
// 脱离父的取消链和 deadline（Deadline() 返回 ok=false），但保留 trace ID 等 value 数据
asyncCtx, asyncCancel := context.WithTimeout(detachedCtx, 10*time.Second)
// 注意：asyncCancel 由异步任务自己管理生命周期，不要在当前函数 defer
go func() {
    defer asyncCancel()
    sendAuditLog(asyncCtx, event)
}()

这是一个刻意的设计决定，你明确告诉 Go：“我知道父可能取消，但这个任务必须跑完。” Go 1.21 前社区常用自定义 struct 包装一个不响应取消的 context，升级后直接用官方 WithoutCancel 即可。

3. deadline 在调用链中持续衰减

第 1 章看的是单进程内等待吃预算。现在把视角拉到分布式调用链，同一个 deadline 在多跳间持续衰减，问题更隐蔽也更难定位。

在微服务架构中，一个请求可能经过 3-5 跳：Gateway → Service A → Service B → DB。如果 Gateway 设了 5 秒 deadline，每一跳的网络传输和处理都在吃这 5 秒。

以下在单进程内模拟多服务间的时间消耗。真实跨服务场景中，deadline 的传播依赖协议支持（gRPC 自动、HTTP 需手动，第 4 章详述）。

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

deadline, _ := ctx.Deadline()
fmt.Printf("Service A 设 5s, deadline: %s\n\n", deadline.Format("15:04:05.000"))

// 网络传输 1s 到 Service B
time.Sleep(1 * time.Second)
fmt.Printf("Service B 收到请求:\n")
fmt.Printf("  deadline 仍然是: %s\n", deadline.Format("15:04:05.000"))
fmt.Printf("  剩余时间: %v\n\n", time.Until(deadline).Round(time.Millisecond))

// B 处理 2s 后转发给 Service C
time.Sleep(2 * time.Second)
fmt.Printf("Service C 收到请求:\n")
fmt.Printf("  deadline 仍然是: %s\n", deadline.Format("15:04:05.000"))
fmt.Printf("  剩余时间: %v\n", time.Until(deadline).Round(time.Millisecond))

运行结果：

Service A 设 5s, deadline: 11:34:26.472

Service B 收到请求:
  deadline 仍然是: 11:34:26.472
  剩余时间: 3.999s

Service C 收到请求:
  deadline 仍然是: 11:34:26.472
  剩余时间: 1.993s

A 设了 5 秒，经过传输和处理，C 拿到的只剩不到 2 秒。deadline 是固定在 11:34:26.472 这个绝对时刻，所有服务看到的是同一个 deadline，但各自剩余的时间越来越少。

为什么用绝对时间而不是相对时间？

如果用"剩余时间"传播（比如传 remaining: 4000ms），每一跳都有测量误差：发送方计算 remaining 的时刻和接收方重建 context 的时刻之间有时间差。跳数越多，误差累积越大。

用绝对时间点的好处是精确，前提是各服务时钟基本同步。在同一个数据中心内（NTP，即 Network Time Protocol 同步，通常 < 1ms 误差），这个假设成立。跨地域部署时需要格外注意时钟偏差。

怎么办：

设计调用链超时时，要预留每一跳的"消耗”：

• Gateway timeout = 下游服务 SLA + 网络 RTT（Round-Trip Time，网络往返延迟）× 跳数 + buffer
• 如果链路有 3 跳，每跳网络 50ms、处理 200ms，Gateway 设 5s 时，最末端服务实际可用约 5s - 3×250ms = 4.25s

不要在最末端服务看到"我设了 5s"就以为真有 5 秒，看 time.Until(deadline)，这才是你实际剩余的时间。

另外如果你在调用链中间环节用 WithTimeout 套了一个新 timeout，但传入的 parent context 已经有更早的 deadline，新 timeout 不会"刷新"，而是取两者中更早的那个（和第 2 点一样的逻辑）。所以在中间环节不要随意再套 WithTimeout，除非你确定新 timeout 比 parent 的剩余时间更短。

4. gRPC 自动传播 deadline，HTTP 不会

你以为：在入口设了 timeout，整条调用链都有超时保护。

实际：gRPC 自动帮你传播 deadline（通过 grpc-timeout metadata header），HTTP 不会。在 gRPC + HTTP 混合架构中，超时保护在 HTTP 边界上会静默断裂。

这个坑隐蔽在于：系统正常时完全看不出来。一旦下游变慢，HTTP 那条链路上游早就超时返回了，下游还在慢慢跑。

先看对比：

gRPC 的行为：当你通过 gRPC client stub 发起调用时（如 pb.NewOrderClient(conn).CreateOrder(ctx, req)），框架会自动处理 deadline 传播：

ctx(deadline) → grpc-timeout header → 下游自动重建 ctx

具体过程：读取 ctx 的 deadline → 计算剩余时间 → 编码为 grpc-timeout metadata header → 发送给下游。下游 gRPC handler 收到请求时，框架自动用这个 header 重建 ctx，ctx.Deadline() 返回 ok=true。整个过程对开发者完全透明。

HTTP 的行为：当你调用 http.Client.Do(req.WithContext(ctx))：

ctx(deadline) → ??? → 下游 ctx.Deadline() 返回 ok=false

client 端的 ctx 控制的是本次 HTTP 请求的超时（等响应的时间），但 HTTP 协议本身不传播任何 deadline 信息。下游 HTTP handler 的 request.Context() 是服务器自己创建的 context，它根本不知道上游还有多少时间。

混合架构中的后果：

假设你有这样的调用链：

[API Gateway] --gRPC--> [Order Service] --HTTP--> [Payment Service]
       5s timeout              ↓ 自动传播             ↗ 没有 deadline！

Gateway 设了 5s timeout。Order Service 通过 gRPC 收到请求，ctx 带有 deadline（正常）。然后 Order Service 用 HTTP 调 Payment Service，deadline 丢了。Payment Service 以为没人催，慢慢处理了 30 秒。而 Gateway 在 5 秒时就超时返回了。

结果：用户早就看到超时错误了，Payment Service 还在忙活（而且可能执行了扣款，但上游已经返回失败了）。这就是"超时不传播"导致的部分执行 + 状态不一致，比单纯的超时错误还难排查。

正确姿势：

在 HTTP 调用中手动传播超时：

// 发送端：把剩余时间编码到 header
func propagateTimeout(ctx context.Context, req *http.Request) {
    if deadline, ok := ctx.Deadline(); ok {
        remaining := time.Until(deadline)
        if remaining > 0 {
            req.Header.Set("X-Request-Timeout-Ms",
                strconv.FormatInt(remaining.Milliseconds(), 10))
        }
    }
}

// 接收端：从 header 重建 context，注册为 middleware
func TimeoutPropagationMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()
        if ms := r.Header.Get("X-Request-Timeout-Ms"); ms != "" {
            timeout, err := strconv.ParseInt(ms, 10, 64)
            if err == nil && timeout > 0 {
                var cancel context.CancelFunc
                ctx, cancel = context.WithTimeout(ctx, time.Duration(timeout)*time.Millisecond)
                defer cancel()
                r = r.WithContext(ctx)
            }
        }
        next.ServeHTTP(w, r)
    })
}

此方案用相对时间传播，存在网络传输延迟误差。对同数据中心（<5ms RTT）场景已足够；跨地域可考虑传绝对时间戳（需时钟同步）或接收端主动减去预估 RTT/2。

有些团队选择直接在 HTTP client 的 transport 层做这件事，封装一个 TimeoutPropagatingTransport，这样调用方完全无感知。不管在哪一层实现，核心逻辑就是：发送端算剩余时间放 header，接收端从 header 重建 context。

5. DB 连接池超时和 context 超时会打架

第 1 章说的是通用等待吃时间，这里聚焦一个特别容易误判的场景：DB 连接池排队占时不反映在慢查询日志里，导致排查走弯路。

我踩这个坑的时候花了两天排查。连接池 20 个连接，一个被遗忘的定时任务在每分钟的第 0 秒批量写入，占满连接 3-4 秒。正常请求 QPS 约 200，撞上这个窗口就排队超时。慢查询日志干干净净，网络延迟正常，DB 负载正常。直到有人看了一眼 db.Stats().WaitDuration，原来连接池排队占了 90% 的时间。

db.QueryRowContext(ctx, ...) 的 ctx timeout 包含的不只是查询执行时间，还包括等连接池分配连接的时间。连接池满时，你的 5 秒超时可能 4 秒都在排队等连接。

来看实测：

db.SetMaxOpenConns(1) // 模拟极端情况：连接池只有 1 个连接

// goroutine-1: 占住唯一连接，执行 4s 慢事务
go func() {
    tx, _ := db.BeginTx(context.Background(), nil) // 刻意用 Background() 不受外部 timeout 限制
    time.Sleep(4 * time.Second)
    tx.Commit()
}()

time.Sleep(100 * time.Millisecond) // 确保 g1 先拿到连接

// goroutine-2: 带 5s timeout 来查询
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

start := time.Now()
deadline, _ := ctx.Deadline()
row := db.QueryRowContext(ctx, "SELECT 1") // 开始等连接...
waitTime := time.Since(start)

fmt.Printf("等连接池花了: %v\n", waitTime.Round(time.Millisecond))
fmt.Printf("context 剩余: %v\n", time.Until(deadline).Round(time.Millisecond))

运行结果：

等连接池花了: 3.901s
context 剩余: 1.099s
结论: 你以为有 5s 做查询，实际等排队花了 3.9s，查询只剩 1.1s

这里有三层超时在打架：

三者是嵌套关系：context 超时 ⊃ 连接池等待 ⊃ 查询执行。任何一层先到期，整个操作结束。但开发者通常只关注 context 超时那一层，完全忘了连接池等待也在吃时间。

为什么慢查询日志看不出来？

MySQL/PostgreSQL 的慢查询日志记录的是查询开始执行后的耗时，从 DB 引擎开始处理 SQL 的时刻算起，不包括等连接池的时间。所以从 DBA 的视角看，所有查询都很快（0.1s），系统健康得很。但从应用层看，客户端频繁超时。

怎么办：

1. 监控连接池等待时间：db.Stats() 返回的 WaitDuration 是等连接池的累计时间。如果这个值增长很快，说明连接池是瓶颈
2. 分离超时设置：context timeout 设"业务能接受的最大等待时间"（包含排队），DSN 的 readTimeout 设"查询本身的极限时间"。两者配合
3. 连接池调优：增大 MaxOpenConns、缩短 ConnMaxIdleTime（减少僵尸连接）、监控 InUse vs MaxOpenConns 的比率
4. 考虑快速失败：如果等连接超过某个阈值（比如 1s），不如直接返回 503 让客户端重试，而不是继续等
5. 区分超时原因：使用 context.WithTimeoutCause(ctx, 5*time.Second, fmt.Errorf("db query timeout")) 可在 context.Cause(ctx) 中拿到具体是哪层超时触发了取消，区分连接池等待超时 vs 查询执行超时

出门检查清单

下次写 context.WithTimeout 之前，用这 5 条过一遍：

• WithTimeout 放在真正做事的位置了吗？前面有排队的话，预算够用吗？
• 子 timeout 比父短吗？比父长等于没设。需要脱离就用 WithoutCancel。
• 跨服务调用留够衰减余量了吗？用 time.Until(deadline) 看实际剩余。
• HTTP 边界手动传播了吗？gRPC 自动，HTTP 要自己加 middleware。
• DB 连接池排队时间算进 timeout 了吗？慢查询日志不含排队时间。

这 5 条不是"高级技巧"。它们是 context.WithTimeout 的基本行为，只是文档不会这么直白地告诉你，而你不踩坑就不会想到。

context.WithTimeout 的设计是合理的，绝对时间点比相对时间更精确，最短者胜防止资源泄漏，gRPC 层面的自动化传播减少人为遗漏。问题不在 Go 的设计，在于我们的心智模型太粗糙了。

建议现在 grep 一下你服务里的 WithTimeout，用上面 5 条逐个过一遍。特别关注 HTTP 边界和 DB 查询这两个高发区。

原文发布于 止语Lab