Go 怎样给单个处理器增加超时边界

给单个 Go HTTP 处理器增加时间上限，最小改法是用 http.TimeoutHandler 包一层。处理器在时间内完成时，客户端得到原本的响应；超过时间后，包装器返回 503 Service Unavailable 和指定消息。真正容易遗漏的是：超时只解决“客户端何时收到失败响应”，下游查询、远程调用和循环任务仍然要通过请求上下文协作停止。

官方文档：https://pkg.go.dev/net/http#TimeoutHandler

本文把这件事看成一次局部迁移：从没有单处理器边界的旧写法，迁移到标准库包装器，并补齐上下文、响应能力和回归检查。范围只覆盖 TimeoutHandler 的响应行为与上下文取消，不讨论第三方路由器或整台服务器的连接超时。

先确定需要迁移的是哪一层超时

http.TimeoutHandler 适合“某一个路由或处理器不能占用请求太久”的场景，例如报表查询、依赖外部服务的聚合接口或单次计算。它接收一个已有的 http.Handler、一个 time.Duration 和超时消息，返回另一个可以注册到路由上的处理器。

这和 http.Server 的 ReadTimeout、WriteTimeout 不是同一层。服务器字段约束连接或读写阶段，适合统一的基础设施边界；TimeoutHandler 把差异留在某一个处理器上。迁移前先把“请求读得太慢”“响应写得太慢”和“业务计算太久”分开，否则很容易给所有接口套同一个数值。

用 TimeoutHandler 包装单个处理器

下面的包装器把五百毫秒作为示例边界，并把超时文本设成稳定、可观察的短消息。注册时只替换目标处理器，其他路由不受影响。

package main

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

func reportHandler(w http.ResponseWriter, r *http.Request) {
	// 真实项目中这里应把 r.Context() 传给查询或远程调用。
	fmt.Fprintln(w, "report ready")
}

func main() {
	// 只给报表处理器设置局部时间边界，不改变其他路由。
	report := http.TimeoutHandler(
		http.HandlerFunc(reportHandler),
		500*time.Millisecond,
		"report timeout",
	)

	// 通过局部 mux 注册包装后的处理器。
	mux := http.NewServeMux()
	mux.Handle("/report", report)

	// ListenAndServe 返回错误时交给上层记录或退出。
	if err := http.ListenAndServe(":8080", mux); err != nil {
		panic(err)
	}
}

超过五百毫秒时，客户端看到的是 503，而不是处理器稍后写出的 200。官方文档还说明，超时之后，被包装处理器对 ResponseWriter 的写入会返回 http.ErrHandlerTimeout；因此不能把超时后的写入当成仍会送达客户端的正常响应。

把请求上下文继续传给慢操作

超时包装器不能替业务代码强行停止任意 goroutine。可取消的数据库查询、HTTP 调用和分段计算，都要接收 context.Context，并在等待或循环中观察取消信号。当前标准库实现会让包装后的请求拥有与时间边界相关的取消信号；业务代码是否能及时结束，取决于它有没有把 r.Context() 往下传。

下面用一个可取消的分段工作函数演示边界。它没有接入真实数据库，time.NewTimer 只是模拟每一段工作；实际调用应优先使用支持 context 的 API。

package main

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

var errWorkCanceled = errors.New("work canceled")

func buildReport(ctx context.Context) (string, error) {
	for part := 1; part 

示例故意把每段工作设成 180 毫秒、总边界设成 500 毫秒，因此读者可以看到在第三段附近收到取消。这里的数字只是演示输入，不是性能结论。生产代码应让数据库驱动、HTTP 客户端或消息操作使用自己的 context 版本，不能只在外层包一层再等待不可取消的函数返回。

超时后不要把业务协作取消想成强制杀线程

处理器超时后，客户端侧的 HTTP 响应边界已经确定为 503；但处理器内部启动的工作可能还没有立即返回。若业务代码忽略 ctx.Done()，它仍可能继续占用 CPU、连接或其他资源。正确做法是让每个可等待点都能选择取消分支，并在函数返回前释放资源。

还要注意包装器对响应能力的影响：官方文档明确指出，TimeoutHandler 支持 Pusher，但不支持 Hijacker 或 Flusher。因此依赖逐块刷新、长轮询刷新或连接接管的处理器，不应直接套这层包装器后就认为行为保持不变。

从旧写法迁移时保留这几项检查

如果旧处理器没有任何局部时间边界，迁移时先只包住一个明确的慢接口，再检查三类路径：正常完成、超过边界、客户端提前断开。不要一开始给所有路由统一设置一个很小的数值。

1. 正常完成：处理器在边界内写出 200，返回体和响应头没有因包装器产生意外变化。
2. 超时：客户端收到 503 和指定消息；处理器后续写入不再被当成成功响应。
3. 协作停止：下游操作能观察 ctx.Done()，错误路径会关闭 rows、body、定时器或其他资源。
4. 能力差异：涉及流式写入时检查 http.Flusher；涉及连接接管时检查 http.Hijacker，不能假设包装器继续透传。
5. 日志归因：把 503、上下文截止和下游真实错误分开记录，避免把每次超时都误判成客户端断开。

最小迁移清单可以概括为：先界定单接口的业务时间，再用 TimeoutHandler 包装；把 r.Context() 传过所有可取消调用；把超时当成 503 响应边界；最后确认处理器没有依赖包装器不支持的流式或连接级能力。

TimeoutHandler 超时后一定会杀掉处理器吗？

不会把任意 goroutine 强制杀掉。它负责选择超时响应，并通过请求上下文提供取消信号；业务代码必须主动观察信号并返回。

超时响应为什么是 503？

TimeoutHandler 的标准行为就是在处理器超过时间限制时返回 Service Unavailable。若业务要表达不同的产品语义，可以在外层设计错误模型，但不要把包装器实际返回码误写成 408 或 504。

流式接口能直接用 TimeoutHandler 吗？

需要谨慎。包装器不支持 http.Flusher，依赖逐块刷新到客户端的接口应采用专门的取消与写超时方案，并明确响应提交时机。

只设置 Server.WriteTimeout 够不够？

不一定。它解决的是服务器写响应阶段的连接级边界，不能代替把请求上下文传给数据库、HTTP 客户端和业务循环。单接口需要独立上限时，仍应在处理器层明确表达。

相关官方资料：https://pkg.go.dev/net/http#TimeoutHandler、https://pkg.go.dev/context、https://github.com/golang/go/blob/master/src/net/http/server.go。