Go TimeoutHandler 超时后为什么多打一条日志：return_after_timeout 的关闭边界

服务端给接口套上 http.TimeoutHandler 后，客户端已经收到 503，日志里却又出现一条 superfluous response.WriteHeader，或者测试辅助函数 return_after_timeout 提前收尾。这里最容易混淆的是“响应已经超时”和“处理函数已经停止”不是一回事：TimeoutHandler 只负责切换外层响应，底层 h.ServeHTTP 仍可能在自己的 goroutine 中继续运行。

看到超时后的多余日志，先区分它来自 TimeoutHandler 的 timeoutWriter，还是来自业务处理函数、测试记录器或关闭逻辑；前者有明确的 ctx.Done 边界，后者必须等待自己的完成信号。

TimeoutHandler 把响应边界切在哪里

Go 官方 net/http 文档对 TimeoutHandler 的定义很直接：处理时间超过限制时，外层返回 503，后续业务处理函数写入会得到 ErrHandlerTimeout。当前实现把原始的 ResponseWriter 包成 timeoutWriter，再用带超时的请求上下文调用 h.ServeHTTP。

done := make(chan struct{})
panicChan := make(chan any, 1)
go func() {
    h.ServeHTTP(tw, r)
    close(done)
}()

select {
case p := 

这三个节点的关系决定了“谁先提交响应”：done 先到，说明业务处理完成；ctx.Done 先到，外层立即写入超时响应；panicChan 先到，则把业务 panic 交回服务器处理。超时分支完成后，原始的 h.ServeHTTP 并没有被 Go runtime 中断。

多打一条日志，先看是哪个写入分支

超时分支会给底层 timeoutWriter 设置 tw.err = ErrHandlerTimeout，随后业务函数再调用 Write 时，Write 会在锁内发现 tw.err，直接返回错误，不再把数据追加到外层响应。

WriteHeader 的判断稍有不同。writeHeaderLocked 先看 tw.err，再看 wroteHeader。已经进入错误状态时它会直接返回；如果尚未超时却已经写过响应头，再次调用 WriteHeader 才会触发 superfluous response.WriteHeader。因此，日志出现的时间点比“客户端收到 503”更重要。

return_after_timeout 这类测试辅助函数怎么接

return_after_timeout 不是标准库 net/http 的函数名。如果项目或测试里有同名辅助函数，它通常表达“到时间就让测试继续”，不能被当成业务处理已经结束的证明。正确做法是保留两个信号：一个是请求上下文的 deadline，另一个是业务函数通过 done 或 WaitGroup 发出的完成信号。

测试要复现超时日志时，可以先等待客户端侧的 503，再等待业务完成信号，最后关闭日志缓冲区。若先调用 return_after_timeout 就关闭 recorder、日志 writer 或临时资源，后台的 h.ServeHTTP 仍可能继续写入，于是看到的“多一条日志”其实是测试收尾顺序造成的噪声。

responseDone := make(chan struct{})
handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    defer close(responseDone)
    // 业务工作可能晚于 TimeoutHandler 的 503 返回
})
wrapped := http.TimeoutHandler(handler, 50*time.Millisecond, "timeout")

上线前用三项检查收住超时噪声

第一，给超时响应和业务完成分别打点：记录请求 ID、HTTP 状态、ctx.Err() 和处理函数结束时间。第二，确认业务依赖能响应请求上下文；TimeoutHandler 不会替你停止数据库查询、文件读取或外部调用。第三，把“允许出现的超时写入错误”和“真正的重复响应头”分开告警，避免把正常的 ErrHandlerTimeout 当成服务端故障。

Go 官方源码还明确了两个接口边界：TimeoutHandler 支持 Pusher，但不支持 Hijacker 和 Flusher。如果接口依赖流式刷新或连接劫持，应该重新评估超时包装方式，而不是用日志过滤器掩盖表现。

相关问题

TimeoutHandler 超时后会杀掉业务 goroutine 吗？

不会。它先返回外层 503，并让包装后的写入返回 ErrHandlerTimeout；业务函数是否结束，取决于它自己是否响应上下文和依赖的取消信号。

为什么有时只看到 ErrHandlerTimeout，没有重复响应头日志？

两者不是同一条件。错误状态下的写入会被 tw.err 拦截；重复响应头日志需要在错误状态建立前重复提交响应头。

可以把 return_after_timeout 当成 handler 已完成吗？

不可以。它最多说明等待窗口到了。若要安全关闭测试资源，还要等待业务函数的 done、WaitGroup 或等价完成信号。

排查这类日志时，先沿着 ctx.Done、timeoutWriter 和业务完成信号把时间线拆开，再判断是否真的存在重复响应头。这样既能保留超时保护，也不会因为一次测试收尾过早而误判 net/http 的行为。