Go http.TimeoutHandler 怎样给处理器设置超时兜底

我第一次把慢处理器包进 http.TimeoutHandler 时，最容易误判的一点是：它能让客户端及时收到超时响应，却不会替你杀掉已经开始执行的业务函数。更准确的理解是，TimeoutHandler 在处理器外面加了一层时间边界；超时后返回 503，内部处理器是否收尾，要看它有没有认真监听请求上下文。

给单个处理器设置上限时，可以用 http.TimeoutHandler(handler, duration, message)；但内部工作必须响应 r.Context().Done()，否则只是“客户端先结束，后台继续跑”。

官方地址：https://pkg.go.dev/net/http#TimeoutHandler

先看它解决的是哪一种压力

TimeoutHandler 适合给某个处理器加一条明确的时间预算，例如报表查询、外部接口聚合或后台管理接口。它返回一个新的 Handler，内部仍调用原处理器，但会把请求上下文换成带超时的派生上下文。

这和 http.Server.WriteTimeout 的职责不同：前者贴近一个处理器，适合局部策略；后者属于服务器连接级配置，影响整个服务的写入阶段。把两者混在一起，排查时很容易把“业务超时”和“连接写入超时”当成一个问题。

用上下文感知的处理器接入时间上限

下面的写法把“准备工作”和“真正耗时的工作”都放到可取消分支中。TimeoutHandler 的第三个参数是超时后返回给客户端的响应正文；超时状态码由标准库写成 503。

package main

import (
    "fmt"
    "net/http"
    "time"
)

func reportHandler(w http.ResponseWriter, r *http.Request) {
    // 用请求上下文接收 TimeoutHandler 的截止信号。
    work := time.NewTimer(1500 * time.Millisecond)
    defer work.Stop()

    select {
    case 

这个例子里，客户端等待时间最多约 1 秒；如果 reportHandler 还没有完成，外层会返回 503。更重要的是，内部的 select 也会收到派生上下文的取消信号，所以数据库查询、HTTP 客户端调用或队列等待都应继续向下传递这个上下文。

超时响应返回了，后台工作不一定停止

标准库实现会在内部处理器中使用带期限的上下文，并让处理器在独立执行单元里运行；达到期限后，外层写入 503，内部写入则返回 http.ErrHandlerTimeout。这意味着超时响应已经确定，不代表业务函数已经自然退出。

因此，不能把下面这种写法当成完整治理：先启动一个不接收上下文的慢任务，再用 TimeoutHandler 包住它。它可能让客户端很快看到失败，但慢任务仍然占用连接、数据库并发或 goroutine。正确的做法是让下游 API 接受 context.Context，或者在自有循环中显式检查取消。

func queryHandler(w http.ResponseWriter, r *http.Request) {
    // 把请求上下文继续传给下游，避免只取消外层响应。
    result, err := loadReport(r.Context())
    if err != nil {
        // 超时和客户端取消都不再尝试写一个新的成功响应。
        if r.Context().Err() != nil {
            return
        }
        http.Error(w, "load report failed", http.StatusInternalServerError)
        return
    }
    fmt.Fprintln(w, result)
}

func loadReport(ctx context.Context) (string, error) {
    // 真实实现应把 ctx 传入数据库、RPC 或其它可取消调用。
    select {
    case 

如果下游库不支持取消，就要在架构上限制它的并发和资源生命周期；不要只把返回 503 当作资源已经释放的证明。

流式响应和连接接管是明显的反例

TimeoutHandler 支持 http.Pusher，但不支持 http.Flusher 和 http.Hijacker。所以 SSE、长轮询中需要持续刷新数据的处理器，或需要接管连接做 WebSocket/原始协议升级的处理器，都不应直接套这层包装。

这不是把接口断言写得更复杂就能解决的问题：包装器提供的是自己的响应写入边界，无法把底层的刷新和连接接管能力原样暴露出来。流式场景应选择能理解流生命周期的超时策略；普通接口则可以让业务上下文取消与服务级写入限制各司其职。

我的采用清单

我现在判断是否采用它，只问三个问题：这个处理器是否需要一个独立时间预算？下游工作是否能随上下文退出？响应是否依赖持续刷新或接管连接？前两个答案是“能”，且第三个是“否”时，TimeoutHandler 才是清晰的局部模式。

常见延伸问题

超时后内部处理器会被强制终止吗？

不会。它能收到派生上下文的取消信号，但是否退出取决于处理器和下游调用是否配合。

超时正文可以自定义吗？

可以，把自定义字符串传给第三个参数；传空字符串时，标准库会使用默认超时正文。

为什么超时后再次 Write 会报错？

超时后内部写入会返回 http.ErrHandlerTimeout。此时外层 503 已经写出，不应再尝试把它改成成功响应。