Go context 超时控制实战：从接口入口到 goroutine 回收的完整流程

Go 项目里，慢接口最容易把问题扩散成一串连锁反应：HTTP 请求已经超时，DB 查询还在跑，远程调用还在等，goroutine 也没有及时退出。用户看到的是接口慢，服务端看到的是连接、协程和资源慢慢堆起来。

context 的价值就在这里：它把取消信号、超时时间和请求范围串起来，让一条调用链知道什么时候该停止。本文按完整工作流讲解：从接口入口设置超时预算，到传给 DB 和远程请求，再到 goroutine 主动响应取消并释放资源。

目标和边界

本文讨论的是 Go 服务端常见的 context 超时和取消控制。我们不展开 context 源码实现，也不把主题扩展成完整分布式链路治理。读完后，你应该能完成三件事：

1. 在 HTTP 入口为每个请求设置合理的超时预算。
2. 把 ctx 传到 DB 查询、远程请求和后台 goroutine。
3. 用测试和日志确认取消信号真的触发了资源回收。

先说结论：context 不是用来存所有业务参数的全局背包，它更适合传递请求范围内的取消、超时和少量跨边界值。真正要做稳，是让每一层都接收 ctx，并在可能阻塞的位置主动响应 ctx.Done()。

全流程总览

一条健康的 Go 请求链路，可以按五步理解：入口 ctx、超时预算、传给 DB、监听 Done、释放资源。只在入口创建 context 不够，后面的 DB 查询、远程请求和 goroutine 都要接住这个信号。

阶段一：在入口定义超时预算

目标

入口层先决定这个请求最多能花多少时间。没有统一预算，后面每一层都会按自己的节奏等待，最终就是接口慢、资源占用高、用户体验差。

关键动作

在 HTTP handler 里从请求 context 派生一个带超时的 ctx，并且立刻安排 cancel。即使请求提前结束，也能及时释放内部计时资源。

func userHandler(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 800*time.Millisecond)
    defer cancel()

    user, err := loadUser(ctx, r.URL.Query().Get("id"))
    if err != nil {
        http.Error(w, err.Error(), http.StatusGatewayTimeout)
        return
    }

    json.NewEncoder(w).Encode(user)
}

常用工具/代码选择

入口超时不要随手写一个很大的数。可以按接口目标拆分：轻量读接口 300 到 800ms，复杂聚合接口 1 到 3 秒，批处理走异步任务，不要占用在线请求链路。

检查点

每个对外接口都应该能说清楚：总超时是多少，DB 占多少预算，远程请求占多少预算，超时后返回什么状态和日志。

阶段二：把 ctx 传给 DB 查询和远程请求

目标

入口创建了 ctx 只是第一步。真正能不能取消，取决于下游调用是否使用了支持 context 的 API。

关键动作

DB 查询要使用带 Context 的方法，例如 QueryContext。远程 HTTP 请求也要把 ctx 绑定到请求对象上。

func loadUser(ctx context.Context, id string) (User, error) {
    row := db.QueryRowContext(ctx,
        "SELECT id, name FROM users WHERE id = ?",
        id,
    )

    var u User
    if err := row.Scan(&u.ID, &u.Name); err != nil {
        return User{}, err
    }
    return u, nil
}

func callProfile(ctx context.Context, url string) (*http.Response, error) {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return nil, err
    }
    return http.DefaultClient.Do(req)
}

常用工具/代码选择

函数签名建议把 ctx context.Context 放在第一个参数。这样代码审查时很容易看出某个方法是否参与请求取消链路。

检查点

搜索核心链路里的 DB 查询、远程 HTTP、缓存访问、消息发送，确认它们是否能接收 ctx。不能接收 ctx 的依赖，要在外层加时间限制或隔离。

阶段三：让 goroutine 主动响应取消

最容易被忽略的地方，是 handler 里临时启动的 goroutine。请求已经结束，但 goroutine 没监听取消信号，就会继续跑，甚至一直占着资源。

目标

让每个可能长时间等待的 goroutine 都能在 ctx 取消时退出。

关键动作

在 select 里监听 ctx.Done()。如果 goroutine 还会等待 channel、ticker 或外部结果，就把取消分支和业务分支放在同一个 select 里。

func watchStatus(ctx context.Context, in 

如果使用 ticker，也要在函数退出时停止它：

func poll(ctx context.Context) {
    ticker := time.NewTicker(200 * time.Millisecond)
    defer ticker.Stop()

    for {
        select {
        case 

常用工具/代码选择

短生命周期任务直接使用请求 ctx；长生命周期后台任务建议使用服务级 ctx，在服务关闭时统一取消。不要把一次 HTTP 请求的 ctx 传给需要长期存在的任务。

检查点

压测请求超时场景时，goroutine 数量应该先上升后回落，而不是一直涨。日志中也应该能看到取消原因，而不是只有业务错误。

阶段四：验证超时是否真的生效

目标

context 相关代码很容易“看起来写了，实际上没传到底”。所以必须用测试和观测验证。

关键动作

写一个很短超时的测试，让慢任务在 ctx 取消后退出。下面的例子验证函数会在超时时返回，而不是继续等待。

func TestTimeoutReturn(t *testing.T) {
    ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
    defer cancel()

    start := time.Now()
    err := waitOrStop(ctx, 200*time.Millisecond)
    if err == nil {
        t.Fatal("want timeout error")
    }
    if time.Since(start) > 100*time.Millisecond {
        t.Fatal("return too late")
    }
}

func waitOrStop(ctx context.Context, d time.Duration) error {
    timer := time.NewTimer(d)
    defer timer.Stop()

    select {
    case 

常用工具/代码选择

测试看行为，日志看链路，指标看资源。建议记录请求耗时、超时次数、ctx 错误类型、DB 查询耗时和 goroutine 数量趋势。

检查点

验证通过的标准是：超时请求按预期返回，下游调用不继续占用资源，goroutine 数量能回落，日志能说明是超时还是上游主动取消。

我的推荐流程

1. 先给每个在线接口定义总超时预算，不要让请求无限等待。
2. 所有业务函数签名统一把 ctx context.Context 放第一个参数。
3. DB 查询使用 QueryContext，HTTP 请求使用 NewRequestWithContext。
4. 所有循环、等待 channel、ticker 的 goroutine 都监听 ctx.Done()。
5. 创建派生 ctx 后立刻安排 cancel，避免计时资源滞留。
6. 用测试模拟超时，用压测观察 goroutine 和连接数是否回落。

容易踩坑

落地速查表

总结一下，Go context 超时控制不是在入口包一层 WithTimeout 就结束了。真正完整的流程，是入口定义预算、下游接收 ctx、阻塞点响应 Done、退出时释放资源，并用测试和指标确认这条链路真的生效。