http.TimeoutHandler 超时后为何还会出现多次写入

如果日志里看到 http.TimeoutHandler 超时后仍然出现多次 Write，先不要把它理解成客户端收到了多份响应。这里通常混在一起的是三件事：处理器 goroutine 还在循环、每轮都调用了一次 Write，以及超时包装器已经向客户端写过一次 503。

TimeoutHandler 能控制的是响应出口，不是强制终止业务函数。超时发生后，外层会返回 503 和超时消息；原处理器仍可能继续执行，但它拿到的包装版 ResponseWriter 会让后续写入返回 http.ErrHandlerTimeout。因此正确的修复方向是让业务处理尽早响应 r.Context() 的取消，并在写入错误后立即停止。

结论：多次 Write 调用可以真实发生，但超时后的写入不会继续追加到客户端响应。把“调用次数”“日志次数”和“客户端收到的响应”分开统计，才能判断问题。

先判断到底是谁在多次写入

排障时先把现象拆成三层。第一层是客户端：正常的 TimeoutHandler 超时响应是一次 503，正文是传入的 msg，或者空消息时的默认超时页。第二层是处理器：超时前写入会暂存在包装器里，处理器可能在超时后继续调用 Write。第三层是日志：如果代码每次写入都打印一行，日志数量自然可能大于客户端响应数量。

TimeoutHandler 的超时分工

TimeoutHandler 会为请求创建带期限的上下文，并在新的 goroutine 中运行原处理器。它给处理器的不是底层响应写入器，而是一个带互斥保护和缓冲区的包装器。处理器写入时，数据先进入这个包装器；如果处理器在期限内返回，外层再把状态码、响应头和缓冲内容提交给真正的 ResponseWriter。

如果上下文先结束，外层会写入 503 Service Unavailable 和超时消息，然后把包装器的错误状态设为 http.ErrHandlerTimeout。此后处理器再次调用 Write 时，返回值是 0, http.ErrHandlerTimeout，这些字节不会再追加到已经发出的 503 后面。

这也解释了“为什么还会多次写入”：TimeoutHandler 没有也不能安全地杀掉正在执行的 goroutine。它只改变了响应写入器的行为。真正的业务循环、数据库调用或外部请求，如果没有主动检查上下文，仍可能运行到自己的返回点。

让处理器在超时后停止写入

最小修复是同时检查上下文和 Write 的错误。不要只调用 fmt.Fprintln 而忽略返回值，也不要在发现超时后继续打印或构造大块响应。

package main

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

func streamHandler(w http.ResponseWriter, r *http.Request) {
    for i := 0; i 

示例中有两个停止点。第一处是上下文检查，它能在业务计算或下一轮循环前主动退出；第二处是写入错误处理，它覆盖了处理器已经跨过截止时间、但还没来得及读取上下文的窗口。实际项目中，如果循环内部调用数据库或下游 HTTP 客户端，也要把 r.Context() 继续传入这些调用。

按运行信号定位重复写入

不要只在 Write 前打印“准备写入”。建议为每个请求设置一个短请求标识，分别记录写入次数、写入字节数、返回错误和上下文结束原因。这样能看出是业务循环真的多跑了几轮，还是同一条日志被中间件重复打印。

func writeChunk(w http.ResponseWriter, r *http.Request, n int) bool {
    // 先判断请求是否已取消，避免在已知无效的响应上继续准备数据。
    if err := r.Context().Err(); err != nil {
        return false
    }

    written, err := fmt.Fprintf(w, "chunk-%d\n", n)
    if err != nil {
        // 记录请求标识、n、written 和 err，区分超时写入与网络断开。
        return false
    }
    // 只有写入成功后才把本轮计数视为已发送。
    return written > 0
}

需要特别注意：TimeoutHandler 不支持 http.Flusher 和 http.Hijacker。如果业务依赖逐块刷新、长连接升级或 WebSocket，就不应把它当作透明的响应包装器。此时应该在更靠近业务调用的位置使用上下文超时，并由协议层决定如何结束连接。

回滚路径与告警确认

线上出现重复写入时，先保留当前日志字段和请求样本，不要盲目把超时时间调大。可以暂时关闭逐块输出，改为一次性生成结果；如果仍需保留兜底，保留 TimeoutHandler，但让处理器对上下文和写入错误都立即返回。这样回滚只改变输出策略，不会掩盖下游调用本身过慢的问题。

告警至少关注三组指标：超时 503 数量、ErrHandlerTimeout 写入错误数量、超时请求中业务 goroutine 的完成延迟。第一项升高说明响应期限被触发，第二项明显高于第一项说明处理器在超时后仍在循环，第三项持续升高则要继续排查下游调用是否忽略了上下文。

最后的判断

http.TimeoutHandler 的职责是提供一个响应超时兜底：期限到了，外层写 503，内层后续写入返回 http.ErrHandlerTimeout。它不是 goroutine 终止器，也不是把任意处理器变成长连接安全实现的开关。

如果你只看到一次客户端 503 和多条服务端写入日志，优先修复处理器的取消与错误分支；如果你需要流式刷新或连接升级，则应换成适配该协议的超时设计。把三条观测线拆开之后，“多次写入”通常就能落到一个具体的循环或忽略错误的位置。

常见追问

超时后还能不能继续调用 Write？

可以调用，但包装器会返回 http.ErrHandlerTimeout，写入内容不会继续追加到客户端响应。代码应把这个错误当作当前响应已经结束的信号。

TimeoutHandler 会自动停止数据库查询吗？

不会。只有查询驱动和业务代码真正使用了请求上下文，取消才可能向下游传播；处理器仍应检查上下文并结束自己的工作。

为什么不直接把超时时间调大？

调大只能改变触发阈值，不能修复忽略取消、重复写入或下游请求没有超时的问题。先确认写入错误和上下文结束原因，再决定是否调整时限。