Go Context:超时、取消与截止时间向下传

Go Context:超时、取消与截止时间向下传

Hello,我是小兔大白糖。 读完能把 context 当成请求级取消合同,并避免在库边界丢失或滥用 WithValue。

Go Context是请求级取消与截止时间合同:超时要向下传,库边界不要吞掉 ctx。

估计阅读时间:11 分钟

父 Context 超时取消向下传递
父 Context 超时取消向下传递 · 点击查看 SVG 原图

TL;DR:context.WithTimeout 是协作式取消,不是强制杀 goroutine。把 ctx 传到 HTTP/DB/RPC 边界并向上 return err,超时就会 fail-fast;繁琐的 ctx.Err() 主要用在循环和纯 CPU 长任务。WithoutCancel 用于必须完成的副作用。


1. 从一个常见困惑说起:Context 到底解决什么?

很多人(包括有经验的 Go 开发者)都有过类似疑问:

ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel()
 
req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
resp, err := client.Do(req)
if err != nil {
    return err
}
return saveToDB(ctx, resp)

问题清单:

  1. 请求 0s 开始,超过 5s 还没返回,Do() 会报错吗?
  2. 会“中断 HTTP 的 goroutine”吗?
  3. 如果内部逻辑很多,是不是要在每一处都写 if ctx.Err() != nil?
  4. 带了 WithTimeout,后面代码还会继续“偷跑”吗?那 timeout 是不是很鸡肋?
  5. WithoutCancel 又是干什么的?

本文围绕这些问题,讲清楚 Context 的原理、业界用法、以及什么时候该/不该检查 ctx.Err()。


2. Context 是什么:为什么像停工通知单?

context.Context 是 Go 在调用链上传递的三类信号:

信号含义
取消(Cancellation)上游说“别干了”
截止时间(Deadline)最晚做到什么时候
请求级元数据(Values)trace ID、用户信息等(慎用)
go context timeout · 图 2
go context timeout · 图 2 · 点击查看 SVG 原图

核心设计哲学:协作式取消(Cooperative Cancellation)

  • Go 不会像 Thread.interrupt() 那样强制终止 goroutine
  • 超时/取消 = 关闭 ctx.Done() channel,设置 ctx.Err()
  • 下游必须在 I/O 边界 或 循环边界 主动响应

可以把它想象成工地上的广播:“5 分钟后停工!”——听广播的人(HTTP client、DB driver)会停;埋头做纯计算、且从不抬头的人(没传 ctx 的代码)会继续干。


3. 常用 API 怎么选?

3.1 context.WithTimeout(parent, d)

在 d 之后自动触发取消。内部基于 timer + WithCancel。

ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel() // 始终 defer,释放 timer;也允许提前手动取消

适用场景:

  • 单次 RPC / HTTP 调用上限
  • Cron job 整体时间预算
  • 用户-facing API 的 SLA 兜底

3.2 context.WithCancel(parent)

无时间限制,由调用方手动 cancel()。

ctx, cancel := context.WithCancel(parent)
defer cancel()
 
go worker(ctx)
// 某条件满足时:
cancel()

适用场景: 用户点击取消、连接断开、父任务失败需取消兄弟 goroutine(常配合 errgroup)。

3.3 context.WithDeadline(parent, t)

与 WithTimeout 等价,只是用绝对时间点。

3.4 context.WithoutCancel(parent)(Go 1.21+)

返回一个 永远不会因 parent 取消而取消 的 context,但保留 parent 的 values(trace 等)。

go func() {
    // 主请求 5s 超时了,但 Redis 缓存写入仍要完成
    _ = redis.Set(context.WithoutCancel(ctx), key, val, ttl)
}()

适用场景:

  • 审计日志、埋点、通知推送等 best-effort 但不应被父 ctx 掐掉 的副作用
  • 明确知道“主流程失败,清理/记录仍要做”

注意: 这是 显式选择,不是默认行为。滥用会导致“超时了副作用还在跑”。

3.5 context.Background() vs context.TODO()

  • Background():根 context,无取消、无 deadline
  • TODO():占位符,表示“还没想好传什么 ctx”

4. 5s 超时后 HTTP 会怎样?

结论:只有下游真正监听并取消时,HTTP 才会停;只创建 timeout ctx 却不往下传,远端可能继续跑。

ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel()
 
req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
resp, err := client.Do(req)

4.1 时间线

go context timeout · 图 3
go context timeout · 图 3 · 点击查看 SVG 原图

4.2 直接回答你的疑问

疑问答案
超过 5s 会报错吗?✅ 会,errors.Is(err, context.DeadlineExceeded) 通常为 true
会杀掉 HTTP goroutine 吗?❌ 不会 kill。Do() 在调用方 goroutine 阻塞;取消后通过关闭底层连接让 Do() 正常返回 error
后面 saveToDB 还会执行吗?❌ 不会——前提是你 if err != nil { return err }
精确 5.000s 返回?❌ 有几 ms~几十 ms 调度延迟,正常

4.3 Transport 在哪些阶段 respect ctx?

现代 Go net/http 的 Transport 在以下阶段都会检查 ctx:

  • DNS 解析
  • TCP 连接
  • TLS 握手
  • 等待响应头
  • 读取 response body

因此“请求很慢”时,通常会在超时点附近失败,而不是傻等到服务端 30s 超时。


5. 为什么 WithTimeout 有时显得鸡肋?

不是 Context 鸡肋,而是用法让取消信号失效了。

反例 1:吞掉错误,循环继续

for _, chat := range chats {
    if err := updateStatus(ctx, chat); err != nil {
        log.Error(err)
        errorCount++ // 只计数,不 return
    }
}
return nil // 永远“成功”

即使每次 updateStatus 里 HTTP/DB 都 respect ctx 并返回 DeadlineExceeded,外层仍会把所有 chat 跑完。超时保护 形同虚设。

反例 2:没把 ctx 传下去

resp, err := http.Get(url) // 没用 NewRequestWithContext

反例 3:副作用 goroutine 用了 WithoutCancel

go func() {
    notify(context.WithoutCancel(ctx)) // 故意的,但需知晓
}()

正例:串行 I/O + 向上传播 error

func Do(ctx context.Context) error {
    data, err := client.Fetch(ctx, url)
    if err != nil {
        return fmt.Errorf("fetch: %w", err)
    }
    if err := repo.Save(ctx, data); err != nil {
        return fmt.Errorf("save: %w", err)
    }
    return nil
}

5s 到了 → Fetch 失败 → 直接 return → Save 根本不会执行。 这才是 WithTimeout 的设计意图。

go context timeout · 图 4
go context timeout · 图 4 · 点击查看 SVG 原图

6. Context 会不会泄漏?

结论:Context 本身不泄漏;泄漏的是没人接收的 goroutine / 没取消的后台工作。

类型会泄漏吗说明
Timer❌defer cancel() 释放 timer 资源
调用方 goroutine❌正常 return,不是泄漏
Cron 任务跑超过 timeout⚠️不是 ctx 泄漏,是任务没停
重叠 Cron⚠️上次没跑完,下次又触发(需 SkipIfStillRunning)
连接池通常 ❌respect ctx 的 driver 会 abort 并归还连接

7. 什么时候该检查 ctx.Err()?

结论:循环、长临界区与对外调用前检查;纯短 CPU 路径通常不必每行检查。

✅ 不需要(大多数情况)

线性串行流程,每步都是 I/O 且传了 ctx:

a, err := stepA(ctx)
if err != nil { return err }
b, err := stepB(ctx)
if err != nil { return err }

上一步因 DeadlineExceeded 失败 return 后,下一步不会执行。不必每行写 ctx.Err()。

HTTP Server handler: 直接用 r.Context() 往下传即可。

✅ 需要检查

场景原因写法
for 循环 / 批处理两次 I/O 之间可能已超时每次迭代开头 if err := ctx.Err(); err != nil { return err }
长纯 CPU 计算没有 I/O 边界自动取消循环内周期性检查
可选优化:阶段间隙避免启动新的昂贵操作大步骤之间检查
select 多路复用等待 channel 时同时等 ctxselect { case <-ctx.Done(): ... }

批处理推荐写法

for _, item := range items {
    if err := ctx.Err(); err != nil {
        return fmt.Errorf("batch cancelled: %w", err)
    }
    if err := process(ctx, item); err != nil {
        if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
            return err // 超时/取消 → 立即停止
        }
        // 单条业务错误是否 continue,按需求决定
        log.Warn("item failed", "id", item.ID, "err", err)
    }
}

8. 业界常见模式有哪些?

8.1 约定:ctx 作为第一个参数

func (s *Service) GetUser(ctx context.Context, id string) (*User, error)

全公司统一,Code Review 时检查所有 I/O 是否传 ctx。

8.2 并行任务用 errgroup

g, ctx := errgroup.WithContext(ctx)
g.Go(func() error { return callA(ctx) })
g.Go(func() error { return callB(ctx) })
return g.Wait() // 任一失败或 ctx 取消,兄弟任务也被取消

8.3 HTTP 入站 vs 出站

方向做法
入站(Handler)r.Context() 已含客户端断开等信号
出站(调用第三方)WithTimeout 设更紧的子 deadline
func handler(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)
    defer cancel()
    result, err := svc.Process(ctx, ...)
    // ...
}

8.4 Cron / 长任务

// 1. 整体超时
ctx, cancel := context.WithTimeout(ctx, 10*time.Minute)
 
// 2. 防止重叠执行
cron.New(cron.WithChain(cron.SkipIfStillRunning(logger)))
 
// 3. 超时后 return,不要吞 error
if errors.Is(err, context.DeadlineExceeded) {
    return err
}

8.5 gRPC / Kitex / database

  • gRPC:grpc.DialContext、每个 RPC 传 ctx
  • Kitex:生成的 client 方法第一个参数就是 ctx
  • MongoDB:collection.Find(ctx, ...) — driver 原生支持
  • Redis:需使用带 ctx 的 API(如 go-redis 的 Get(ctx, key))

9. 四条实用准则是什么?

go context timeout · 图 5
go context timeout · 图 5 · 点击查看 SVG 原图
  1. I/O 必传 ctx — HTTP、DB、RPC、消息队列
  2. error 必向上 return — 别把 DeadlineExceeded 当普通错误吞掉
  3. 循环才查 ctx.Err() — 线性两步流程不必每步查
  4. 副作用用 WithoutCancel 是显式选择 — 文档化你的理由

10. 快速对照表怎么用?

你以为的实际上
WithTimeout 会自动 return 整个函数只在 respect ctx 的 I/O 返回 error,且你向上 return 时才停
要到处写 ctx.Err()线性 I/O 链不用;循环 / 长 CPU 才需要
超时后会杀 goroutine通过关闭连接让阻塞 I/O 返回 error,goroutine 正常退出
WithoutCancel 是默认行为必须显式使用,用于不能中断的副作用
Context 会泄漏defer cancel() 不会;任务是“没停”不是“泄漏”

11. 总结:带走哪几条?

context.WithTimeout 是 Go 生态里控制延迟和取消的标准解法,并不鸡肋。觉得鸡肋,通常是因为:

  • 错误被吞掉或循环不退出
  • ctx 没传到 I/O 边界
  • 把 WithoutCancel 和“偷跑”混为一谈

记住这个公式:

Timeout + ctx 传入 I/O + error 向上 return = Fail-fast

Timeout + 吞 error + 循环 continue = 形同虚设


参考资料


English version: 24-go-context-timeout-practical-guide.en.md

示例来自生产环境中的 cron job、HTTP+DB 流水线,以及团队里常见的 Context 误解。