ResponseController 如何为流式响应设置单独写超时

长轮询、SSE 和分块下载有一个共同难题：响应可能持续几分钟甚至更久，但一次真正向慢客户端写数据时又不能无限阻塞。只配置 http.Server.WriteTimeout，限制的是整段响应写入；把它设为零或一个很大的值，又会让所有路由失去合适的写保护。

从 Go 1.20 开始，可以用 http.ResponseController 对当前响应设置写期限。流式 Handler 的实用做法是：保留服务器级 WriteTimeout 作为普通接口的基线，在每个输出片段的 Write 与 Flush 前设置一个短的绝对期限，成功后立刻清除。这样限制的是“这次写多久”，而不是“整条流最多活多久”。

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

先看迁移范围：从整段响应限制到单次写入窗口

Server.WriteTimeout 是服务器级配置。官方注释说明，它在读取新请求头时重置，并且不能让 Handler 针对单个请求做决策。普通 JSON 接口通常适合这种统一上限，但长时间存活的流式响应会遇到冲突：如果全局上限较短，连接会在流尚未结束时到期；如果为照顾流式接口而把全局上限拉得很长，普通接口的慢写保护也随之变松。

ResponseController.SetWriteDeadline 把控制权下放到当前 Handler。它设置的是绝对时间点，不是一个自动续期的 duration。传入零值 time.Time{} 表示取消写期限。

旧代码为什么容易在流式响应上失衡

下面的服务器配置本身没有错，问题在于它无法区分普通接口和长流：

srv := &http.Server{
    Addr:              ":8080",
    Handler:           mux,
    ReadHeaderTimeout: 5 * time.Second,  // 限制请求头读取时间
    WriteTimeout:      15 * time.Second, // 对所有响应使用统一写期限
    IdleTimeout:       60 * time.Second, // 限制 keep-alive 空闲时间
}

// 生产代码应处理 ListenAndServe 返回的非 ServerClosed 错误。
if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
    log.Fatal(err)
}

如果某个 SSE 连接设计上要持续几分钟，那么 15 秒的整段写期限显然不合适。常见但代价较大的修改是把 WriteTimeout 改为零。Go 1.20 的发布说明展示过使用 ResponseController.SetWriteDeadline(time.Time{}) 覆盖服务器级期限来发送大型响应，这正说明局部控制比修改全局基线更合适。

另一个旧做法是直接检查 ResponseWriter 是否实现某个可选方法。它不仅分散了能力发现逻辑，还容易被日志、压缩或指标中间件包裹的 writer 截断。ResponseController 会识别底层能力，并沿着标准的 Unwrap() http.ResponseWriter 逐层查找。

新写法：只包住 Write 与 Flush

下面的 SSE Handler 把单次写超时设为 3 秒。第一次写入前先设置期限，这样如果当前 writer 不支持该能力，还来得及返回普通 HTTP 错误。每次成功 Flush 后清除期限，等待下一条消息时不计时。

func streamEvents(w http.ResponseWriter, r *http.Request) {
    rc := http.NewResponseController(w)

    w.Header().Set("Content-Type", "text/event-stream")
    w.Header().Set("Cache-Control", "no-cache")
    w.Header().Set("X-Content-Type-Options", "nosniff")

    // 首次写入前检查当前 ResponseWriter 是否支持写期限。
    if err := rc.SetWriteDeadline(time.Now().Add(3 * time.Second)); err != nil {
        if errors.Is(err, http.ErrNotSupported) {
            http.Error(w, "streaming deadline is not supported", http.StatusInternalServerError)
            return
        }
        http.Error(w, "cannot set write deadline", http.StatusInternalServerError)
        return
    }

    // 首条注释可让响应头尽早发送，并验证 Flush 能力。
    if _, err := io.WriteString(w, ": stream-open\n\n"); err != nil {
        return
    }
    if err := rc.Flush(); err != nil {
        return
    }
    if err := rc.SetWriteDeadline(time.Time{}); err != nil {
        return // 清除期限，空闲等待不计入单次写超时
    }

    ticker := time.NewTicker(15 * time.Second)
    defer ticker.Stop()

    for {
        select {
        case 

这里有两个关键细节。第一，官方文档明确写到：期限已经超出后，再设置新期限不能把它延长。因此不要让短期限覆盖下一次业务等待；要么在旧期限到达前刷新，要么像示例这样在成功 Flush 后清除。第二，期限到达后的 body 写入不会继续阻塞，但如果数据已经进入缓冲区，写操作仍可能成功。流式响应因此不能只检查 Write，还要调用并检查 Flush。

中间件包装器必须保留 Unwrap

如果应用用自定义 writer 记录状态码或字节数，应暴露底层 writer。否则 ResponseController 可能无法找到 SetWriteDeadline、Flush 等能力。

type metricsWriter struct {
    http.ResponseWriter
    status int
}

func (w *metricsWriter) WriteHeader(code int) {
    w.status = code
    w.ResponseWriter.WriteHeader(code)
}

func (w *metricsWriter) Unwrap() http.ResponseWriter {
    return w.ResponseWriter // 让 ResponseController 继续查找底层能力
}

func metrics(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        mw := &metricsWriter{ResponseWriter: w, status: http.StatusOK}
        next.ServeHTTP(mw, r)
    })
}

判断不支持时要用 errors.Is(err, http.ErrNotSupported)，不要用字符串比较，也不要假设错误值一定与 http.ErrNotSupported 直接相等。官方源码中的辅助函数会包装这个错误，使其满足 errors.Is。

回归检查不能只看 Handler 是否返回 nil

迁移完成后，至少覆盖下面几组检查。它们验证的是超时边界，不是业务消息内容：

• 普通接口：确认服务器级 WriteTimeout 仍然生效，没有因为流式需求被全局关闭。
• 正常流：每个片段在期限内完成 Write 与 Flush，片段之间可以长时间等待。
• 慢客户端：客户端停止读取时，当前写操作应在局部期限后结束，Handler 不再长期占用资源。
• 客户端断开：r.Context().Done() 能让等待中的 Handler 退出，不必等到下一次写。
• 包装中间件：启用日志、指标或压缩中间件后，Unwrap 链仍能把能力暴露给 ResponseController。
• 代理链路：反向代理可能继续缓冲，即使 Flush 返回成功，最终用户也不一定立即看到数据；需要单独检查代理的流式配置。

单元测试里常见的 httptest.ResponseRecorder 适合检查 header、状态码和 Flush 调用，但它不是实际网络连接。写期限与慢客户端行为更适合用真实的测试服务器和受控客户端做集成测试。不要把 recorder 上的结果当作套接字期限已经生效的证明。

迁移清单

1. 保留合理的服务器级 WriteTimeout，不要为了少数长流全局设为零。
2. 只在明确的 SSE、分块下载或大型响应 Handler 中创建 ResponseController。
3. 把短写期限放在每次 Write 与 Flush 周围，成功后清除。
4. 同时监听 r.Context().Done()，处理客户端主动断开。
5. 为所有自定义 ResponseWriter 包装器实现 Unwrap() http.ResponseWriter。
6. 用 errors.Is 处理 http.ErrNotSupported，并在写出响应头前决定降级或报错策略。
7. 把应用写期限与反向代理、负载均衡器的空闲超时和缓冲策略分开检查。

几个常见问题

SetWriteDeadline 是持续时长还是绝对时间？

它接收一个绝对的 time.Time。通常用 time.Now().Add(timeout) 计算当前写入窗口，传入零值则取消期限。

只调用 Flush 能防止慢客户端拖住 Handler 吗？

不能。Flush 的职责是刷新服务端缓冲；局部写期限负责给底层写操作设置时间边界。两者应配合使用，并分别处理错误。

可以在期限已经超时后再设置一个新期限继续写吗？

官方文档明确说明不能通过这种方式延长期限。正确策略是在期限到达前完成或刷新，或者在每次写成功后清除期限，让下一次写入创建新的窗口。

ResponseController 可以在 ServeHTTP 返回后继续使用吗？

不可以。它只用于当前 Handler 的响应控制，官方文档明确要求不能在 ServeHTTP 返回后继续使用。

最终原则可以压缩成一句话：全局 WriteTimeout 负责普通请求的安全基线，ResponseController 只为确实需要长生命周期的流式响应建立短而明确的单次写入窗口。