Go context 超时：用于构建快速 API 的实用配方

为什么慢请求会让 API 崩溃

单个慢请求通常并不是“只是慢”。在等待期间，它会保持一个 goroutine 存活，持有用于缓冲和响应对象的内存，并且经常会占用一个数据库连接或池中的一个槽位。当足够多的慢请求堆积时，你的 API 就无法做有用的工作，因为有限的资源都在等待。

你通常会在三个地方感受到它。Goroutine 数量积累导致调度开销上升，整体延迟变差。数据库连接池用光可用连接，即使是快速的查询也会在慢查询后排队。内存因在途数据和部分构建的响应而上升，增加了 GC 工作量。

增加更多服务器通常也不能解决问题。如果每个实例都遇到相同的瓶颈（小的 DB 池、某个慢的上游、共享的速率限制），你只是把队列搬到别处，同时付出更多成本却仍见错误激增。

想象一个会并发调用多个依赖的处理器：它从 PostgreSQL 加载用户，调用支付服务，然后调用推荐服务。如果推荐请求挂起且没有被取消，请求就永远不会完成。虽然 DB 连接可能被归还，但 goroutine 和 HTTP 客户端资源仍被占用。把这情形乘以数百个请求，就会发生慢速崩溃。

目标很简单：设定明确的时间上限，时间到了就停止工作、释放资源并返回可预测的错误。Go 的 context 超时让每一步都有截止时间，这样当用户不再等待时工作就会停止。

用通俗的话说 context 超时

context.Context 是一个你沿着调用链传递的小对象，让每一层都达成一致：这个请求什么时候必须停止。超时是防止某个慢依赖占用服务器资源的常见手段。

一个 context 可以携带三类信息：截止时间（何时必须停止）、取消信号（有人决定提前停止）和一些请求范围内的值（谨慎使用，绝不要放大数据）。

取消不是魔法。context 提供了一个 Done() 通道。当它关闭时，请求被取消或时间已到。尊重上下文的代码会检查 Done()（通常通过 select）并提前返回。你也可以检查 ctx.Err() 来知道为什么结束，通常是 context.Canceled 或 context.DeadlineExceeded。

当想要“在 X 秒后停止”时，用 context.WithTimeout。当你已经知道精确的截止时间时，使用 context.WithDeadline。当父条件应该提前停止工作（客户端断开、用户离开、你已有答案）时，使用 context.WithCancel。

当上下文被取消时，正确的行为虽然简单但很重要：停止工作、停止等待慢 I/O，并返回清晰的错误。如果处理器正在等待数据库查询而上下文结束，应该快速返回并让数据库调用在支持上下文的情况下中止。

在 API 边界设置时间上限

阻止慢请求的最安全位置是流量进入服务的边界。如果一个请求要超时，你希望它可预测地并尽早发生，而不是在占用了 goroutine、数据库连接和内存之后才超时。

从边缘开始（负载均衡器、API 网关、反向代理），为任何请求允许的最长时间设定硬上限。这能保护你的 Go 服务，即便某个处理器忘了设置超时也不会无限挂起。

在 Go 服务器内部，为 HTTP 设置超时，避免服务器无限期等待慢客户端或停滞的响应。至少要配置读取头部、读取完整请求体、写入响应以及保持空闲连接的超时。

为你的产品选择一个默认请求预算。对很多 API 来说，1 到 3 秒是典型请求的合理起点，而导出等已知慢操作可以设更高。具体数值不如保持一致、监测并对例外有明确规则重要。

流式响应需要额外注意。很容易不小心创建一个无限流，服务器一直保持连接并不断写小块数据，或者在发送第一个字节前无限等待。提前决策接口是否真的是流式的。如果不是，就强制执行最大总时长和第一次字节时间上限。

一旦边界有了明确的截止时间，就更容易将该截止传播到整个请求链路。

逐步操作：在 HTTP 处理器中添加超时

最简单的起点是 HTTP 处理器。请求从这里进入系统，因此在这里设置硬上限是很自然的。

1) 派生带时限的 context

创建一个带截止时间的新 context，并确保调用 cancel。然后把这个 context 传给任何可能阻塞的地方：数据库、HTTP 调用或耗时计算。

func (s *Server) GetUser(w http.ResponseWriter, r *http.Request) {
	ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
	defer cancel()

	userID := r.URL.Query().Get("id")
	if userID == "" {
		http.Error(w, "missing id", http.StatusBadRequest)
		return
	}

	user, err := s.loadUser(ctx, userID)
	if err != nil {
		writeError(w, ctx, err)
		return
	}

	writeJSON(w, http.StatusOK, user)
}

2) 在每个阻塞调用中传入 ctx

一个好规则是：如果函数可能等待 I/O，它就应该接受 context.Context。保持处理器可读，把细节推到像 loadUser 这样的辅助小函数里。

func (s *Server) loadUser(ctx context.Context, id string) (User, error) {
	return s.repo.GetUser(ctx, id) // repo should use QueryRowContext/ExecContext
}

3) 在上下文结束时尽早返回

如果达到了截止时间（或客户端断开），停止工作并返回友好的响应。常见映射是将 context.DeadlineExceeded 映射为 504 Gateway Timeout，而 context.Canceled 则表示“客户端已离开”（通常不返回响应体）。

func writeError(w http.ResponseWriter, ctx context.Context, err error) {
	if errors.Is(err, context.DeadlineExceeded) {
		http.Error(w, "request timed out", http.StatusGatewayTimeout)
		return
	}
	if errors.Is(err, context.Canceled) {
		// Client went away. Avoid doing more work.
		return
	}
	http.Error(w, "internal error", http.StatusInternalServerError)
}

这个模式可以防止堆积。一旦计时器到期，链路中每个支持 context 的函数都会收到相同的停止信号并能快速退出。

将截止传播到 PostgreSQL 调用

当处理器拥有带截止的 context 后，最重要的规则很简单：在数据库调用中使用同样的 ctx。这样超时才能真正停止工作，而不仅仅是让你的处理器不再等待。

在 database/sql 中，优先使用支持 context 的方法：

func (s *Server) getUser(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    row := s.db.QueryRowContext(ctx,
        "SELECT id, email FROM users WHERE id = $1",
        r.URL.Query().Get("id"),
    )

    var id int64
    var email string
    if err := row.Scan(&id, &email); err != nil {
        // handle below
    }
}

为数据库选择适配请求预算的超时

如果处理器预算是 2 秒，数据库只应该得到其中的一部分。要为 JSON 编码、其他依赖和错误处理留出时间。一个简单的起点是给 Postgres 30% 到 60% 的总预算。对于 2 秒的处理器截止，这可能是 800ms 到 1.2s。

取消查询时会发生什么

当上下文被取消时，驱动会请求 Postgres 停止查询。通常连接会被返回到连接池并可重用。如果取消发生在网络不良时，驱动可能会丢弃该连接并在后来打开新连接。无论哪种方式，你都避免了 goroutine 无期限等待。

检查错误时，应将超时与真正的数据库故障区分开来。如果 errors.Is(err, context.DeadlineExceeded)，说明超时；如果 errors.Is(err, context.Canceled)，说明客户端已离开，应静默停止。其他错误则是普通的查询问题（语法、缺行、权限等）。

将截止传播到外部 HTTP 请求

如果处理器有截止，出站 HTTP 调用也应该尊重它。否则客户端放弃了，但你的服务还在等待一个慢的上游，继续占用 goroutine、socket 和内存。

用父上下文构建出站请求，这样取消可以自动传播：

func fetchUser(ctx context.Context, url string) ([]byte, error) {
	// Add a small per-call cap, but never exceed the parent deadline.
	ctx, cancel := context.WithTimeout(ctx, 800*time.Millisecond)
	defer cancel()

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return nil, err
	}

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close() // always close, even on non-200

	return io.ReadAll(resp.Body)
}

那种每次调用的小超时是安全网。父请求截止仍然是最终的主宰：一个请求使用一把时钟，外加若干个针对高风险步骤的小帽子。

同时在传输层设置超时。context 会取消请求，但传输层超时能保护你免受慢握手或长期不返回头部的服务器影响。

一个会让团队吃亏的细节：必须在每条路径上关闭响应体。如果你提前返回（状态码检查、JSON 解码错误、上下文超时），依然要关闭响应体。泄露响应体会悄然耗尽连接池使延迟出现“随机”峰值。

举个具体场景：你的 API 调用了支付提供商。客户端在 2 秒后放弃，但上游挂起了 30 秒。如果没有请求取消和传输超时，你会为每个被放弃的请求付出那 30 秒的等待成本。

在整个请求中进行超时预算

一次请求通常会触及多个可能慢的环节：处理器工作、数据库查询以及一个或多个外部 API。如果你给每一步都设定比较宽松的超时，总时间会悄悄增长，直到用户感受到并且服务器开始堆积。

预算是最简单的修复办法。为整个请求设定父截止，然后给每个依赖更小的片段。子截止应该早于父截止，这样你可以快速失败并仍有时间返回干净的错误。

在真实服务中行得通的经验法则：

• 先为请求选择一个总预算（例如面向用户的端点 2 秒）。
• 为处理器开一小段缓冲用于格式化响应等（例如 100 到 200ms）。
• 把剩余时间分配给各个依赖。
• 如果有多个外部调用，为每个设置上限，而不是让某一个耗尽整个预算。
• 如果父上下文只剩 120ms，不要启动一般需要 300ms 的依赖调用。

避免互相斗气的超时堆叠。如果处理器上下文有 2 秒截止而你的 HTTP 客户端有 10 秒超时，你是安全的但会让人困惑；如果反过来，客户端可能无关地提前截断。

对于后台工作（审计日志、指标、邮件），不要重用请求上下文。使用单独的上下文和它自己的短超时，这样客户端取消不会终结重要的清理工作。

常见导致请求挂起的错误

大多数超时相关的 bug 不在处理器里，而是在一两层下方，截止时间悄然丢失。如果你在边界设置了超时却在中间忽略了它，仍然可能出现 goroutine、数据库查询或 HTTP 调用在客户端离开后继续运行的情况。

最常见的模式很简单：

• 丢弃请求上下文，使用 context.Background()（或 TODO）调用下层。这会断开与客户端取消和处理器截止的关联。
• 在循环、重试或 sleep 中不检查 ctx.Done()。请求已取消，但你的代码仍在等待。
• 给每个辅助函数都包一层 context.WithTimeout，导致许多计时器和混乱的截止时间。
• 忘记把 ctx 附加到阻塞调用上（DB 查询、出站 HTTP、消息发布）。如果依赖忽略它，处理器超时毫无意义。
• 把超时当作通用失败并返回 500。客户端需要明确的信号说明请求耗尽了时间。

一个经典失败示例：你在处理器中添加了 2 秒超时，但仓库层用 context.Background() 做数据库查询。在高负载下，慢查询会在客户端放弃后继续运行，堆积随之发生。

修复方法很基础：把 ctx 作为第一个参数传遍调用栈。在长时间运行的工作里，加上快速检查例如 select { case <-ctx.Done(): return ctx.Err() default: }。把 context.DeadlineExceeded 映射为超时响应（通常 504），把 context.Canceled 映射为客户端取消风格的响应（根据习惯通常是 408 或 499）。

在实践中测试与观测超时

只有在你能看到超时发生并确认系统能干净地恢复时，超时才有意义。当某处变慢时，请求应该停止、资源被释放、API 保持可用。

记录重要信息（并保持一致）

为每个请求记录一组相同的小字段，这样你就能比较正常请求和超时请求。包含上下文截止时间（如果存在）以及是什么结束了工作。

有用的字段包括截止时间（或“无”）、总耗时、取消原因（超时或客户端取消）、一个简短的操作标签（"db.query users"、"http.call billing"）和请求 ID。

一个最小模式如下：

start := time.Now()
deadline, hasDeadline := ctx.Deadline()
err := doWork(ctx)
log.Printf("op=%s hasDeadline=%t deadline=%s elapsed=%s err=%v",
  "getUser", hasDeadline, deadline.Format(time.RFC3339Nano), time.Since(start), err)

指标在用户抱怨前暴露超时问题

日志帮助你调试单个请求。指标显示趋势。

跟踪一些在超时配置错误时通常会先升高的信号：按路由和依赖统计的超时次数、在途请求数（在负载下应趋于稳定）、数据库池等待时间，以及按成功/超时拆分的延迟百分位数（p95/p99）。

在本地重现超时（以便你信任修复）

让慢变得可预测。给某个处理器加一个仅用于调试的延迟、在数据库查询中故意延时，或用一个在测试中睡眠的测试服务器包装外部调用。然后验证两件事：你看到了超时错误，且取消后工作很快停止。

一个小的压力测试也有帮助。用 20 到 50 个并发请求运行 30 到 60 秒，强制一个慢依赖。goroutine 数和在途请求数应上升后趋于稳定。如果它们持续攀升，说明某处忽略了 context 取消。

上线前的快速清单

如果超时能发挥作用，就需要在每个可能等待的地方应用它。上线前对代码库做一遍检查，确认每个处理器都遵循相同规则。

• 每个传入请求在边界（路由、中间件、处理器）都有明确的时间预算。没有无限处理器。
• 每个数据库查询都接收请求上下文（或子上下文），并在错误处理中区分 context.DeadlineExceeded 与 context.Canceled。
• 每个出站 HTTP 调用使用 http.NewRequestWithContext（或 req = req.WithContext(ctx)），客户端/传输层配置了超时（拨号、TLS、响应头等待）。避免在生产路径中依赖 http.DefaultClient。
• 错误映射一致：超时每次都变成相同的 API 响应（通常 504），客户端取消清晰映射（通常 499 或 408），并且不要把底层驱动错误直接泄露。
• 日志和指标让超时一目了然：处理器名、耗时，以及哪个依赖超时。

在发布前做一次“慢依赖”演练是值得的。给一次 SQL 查询加入 2 秒的人为延迟，确认三件事：处理器按时返回、数据库调用实际停止（而不是仅处理器停止）以及日志明确记录这是一次 DB 超时。

一个现实示例：一个请求，三个慢依赖

想象一个像 GET /v1/account/summary 的端点。一次用户操作触发三件事：一个 PostgreSQL 查询（账户及最近活动）和两个外部 HTTP 调用（比如计费状态检查和资料丰富化）。

给整个请求一个硬性的 2 秒预算。没有预算时，一个慢依赖就能把 goroutine、数据库连接和内存绑住，直到你的 API 到处开始超时。

一个简单的分配可能是：数据库查询 800ms，外部调用 A 600ms，外部调用 B 600ms。

一旦知道整体截止，把它向下传递。每个依赖得到自己的更小超时，但仍继承父级的取消信号。

func AccountSummary(w http.ResponseWriter, r *http.Request) {
  ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
  defer cancel()

  dbCtx, dbCancel := context.WithTimeout(ctx, 800*time.Millisecond)
  defer dbCancel()

  aCtx, aCancel := context.WithTimeout(ctx, 600*time.Millisecond)
  defer aCancel()

  bCtx, bCancel := context.WithTimeout(ctx, 600*time.Millisecond)
  defer bCancel()

  // Use dbCtx for QueryContext, aCtx/bCtx for outbound HTTP requests.
}

如果外部调用 B 变慢到了 2.5 秒，你的处理器应在 600ms 停止等待、取消正在进行的工作并返回清晰的超时响应给客户端。客户端看到的是快速失败，而不是一直转圈等待。

你的日志应清楚显示哪个环节用了预算，例如：DB 快速完成、外部 A 成功、外部 B 达到上限并返回 context deadline exceeded。

下一步：在整个 API 中标准化超时

一旦某个真实端点在超时和取消上表现良好，把它变成可复用的模式。端到端应用它：处理器截止、数据库调用和出站 HTTP。然后把相同结构复制到下一个端点。

如果把乏味的部分集中起来会更快：边界超时助手、确保 ctx 被传递到 DB 和 HTTP 调用的封装、以及统一的错误映射和日志格式。

如果你想快速原型这个模式，Koder.ai (koder.ai) 可以从聊天提示生成 Go 处理器和服务调用，并导出源码以便你应用自己的截止中间件和预算规则。目标是保持一致性：慢调用尽早停止、错误格式相同，调试不依赖于谁写了端点。