Go http.ResponseController 如何设置请求读写截止时间：连接级超时与错误处理

上传接口偶尔被慢客户端拖住时，单纯把 http.Server.ReadTimeout 调小并不总是合适：有些请求头很快到达，真正慢的是请求体；流式响应则相反，问题出在写回客户端。http.ResponseController 允许处理器在这两个位置设置连接级截止时间，但超时只是让后续读写返回错误，并不会替业务自动取消。

需要限制某一次请求的读取或响应写出时长时，用 NewResponseController(w) 获取控制器，再调用 SetReadDeadline 或 SetWriteDeadline；超时后必须检查读写错误，不能只看 HTTP 状态码。

先分清请求读超时和响应写超时

这两个方法都操作同一条 HTTP 连接的时间边界，但观察点不同。慢上传发生在 Request.Body，慢下载或客户端接收窗口过小则发生在 ResponseWriter。控制器本身不会改变路由，也不会把底层错误转换成某个固定的业务状态码。

官方实现会从当前的 ResponseWriter 开始查找能力；如果中间件包装器实现了 Unwrap，就继续向里找。找不到对应能力时，返回可匹配 http.ErrNotSupported 的错误。因此，先判断返回值，再决定是否继续，是比忽略错误更稳妥的写法。

慢上传场景：让 Request.Body 在指定时刻停止等待

假设接口只接受一个不大的文本请求，但客户端可能长时间分段上传。处理器进入后先给整个请求读取设置截止时间，然后再从 Request.Body 读取内容：

func upload(w http.ResponseWriter, r *http.Request) {
    rc := http.NewResponseController(w)
    deadline := time.Now().Add(8 * time.Second)
    if err := rc.SetReadDeadline(deadline); err != nil {
        http.Error(w, "read deadline unsupported", http.StatusNotImplemented)
        return
    }

    body, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "request body timeout", http.StatusRequestTimeout)
        return
    }
    _, _ = w.Write([]byte(strconv.Itoa(len(body))))
}

这里的关键不是“8 秒后 handler 自动结束”，而是到点后继续读取请求体会得到错误。io.ReadAll 把多次读取合并成一次结果，所以生产代码仍应限制正文大小，例如先用 http.MaxBytesReader 防止客户端用大体积数据绕过时间问题。

图中的调用链对应上面的真实代码：Handler 先调用 NewResponseController，再调用 SetReadDeadline；随后 Request.Body 负责读取，截止时间到达时进入错误分支。

流式响应场景：写出停滞时停止阻塞

流式接口通常会循环写出小块数据。客户端网络变慢时，写调用可能等待发送窗口；可以在开始写之前设置写截止时间：

func stream(w http.ResponseWriter, r *http.Request) {
    rc := http.NewResponseController(w)
    if err := rc.SetWriteDeadline(time.Now().Add(5 * time.Second)); err != nil {
        http.Error(w, "write deadline unsupported", http.StatusNotImplemented)
        return
    }

    for _, part := range []string{"part-1\n", "part-2\n", "part-3\n"} {
        if _, err := w.Write([]byte(part)); err != nil {
            return
        }
        if err := rc.SetWriteDeadline(time.Now().Add(5 * time.Second)); err != nil {
            return
        }
    }
}

每次成功写出后重新设置截止时间，表达的是“下一段最多再等 5 秒”。如果只在循环前设置一次，那么后续分片共享同一个绝对截止点，越靠后的分片越容易立即失败。文档还提醒，超时后的写入可能因为数据已经在缓冲区而成功，所以不能把一次成功写入理解成客户端已经完整收到。

这张图只保留响应写出的核心路径：SetWriteDeadline 设定边界，ResponseWriter 逐段写入；写入错误出现时停止后续分片，而不是继续循环制造更多等待。

包装器、协议和生命周期的三个边界

中间件包装了 ResponseWriter 怎么办

把包装后的 ResponseWriter 传给 NewResponseController 仍然可能工作，前提是包装器提供返回原始对象的 Unwrap 方法。若包装器既没有目标方法也没有 Unwrap，就应接受 ErrNotSupported，不要把失败当成“超时已开启”。

HTTP/1 和 HTTP/2 是否完全一样

方法的调用方式相同，但底层传输和缓冲行为不同。文章中的时间值是示例边界，不是所有协议、代理和客户端都适用的统一推荐值，最终应在真实连接上观察读写错误和请求日志。

handler 返回后还能继续设置吗

不能。Go 官方源码明确说明 ResponseController 不应在 Handler.ServeHTTP 返回后继续使用。需要后台任务时，应在 handler 内完成连接控制，后台任务只处理已经复制出的业务数据。

常见排查顺序

1. 先确认卡住的位置是 Request.Body.Read 还是 ResponseWriter.Write，不要先改同一个全局参数。
2. 记录截止时间设置是否返回 ErrNotSupported，并检查中间件是否保留了 Unwrap。
3. 在错误分支记录请求路径、已读字节数或已写分片数，再决定返回状态或直接结束处理。
4. 配合正文大小限制和服务端整体超时做压测，确认新边界没有把慢请求集中推向下游队列。

相关问题

SetReadDeadline 会取消 context 吗？

不会。它影响后续请求读取；如果业务还依赖取消信号，仍需单独设计 context 和清理路径。

设置了写截止时间，Write 一定会返回超时错误吗？

不一定。已经写入缓冲区的数据可能先成功，只有实际写出受阻时才更可能暴露错误。

能不能用一个截止时间覆盖整个 handler？

不建议这样理解。ResponseController 的两个方法分别约束读和写；handler 的总执行时长还需要服务端超时、context 或业务计时共同管理。

小结

http.ResponseController 适合处理“某条连接在某个阶段不能无限等待”的问题。慢上传看 Request.Body 和 SetReadDeadline，流式输出看 ResponseWriter 和 SetWriteDeadline；每次调用都检查能力错误，每次读写都保留错误分支，配置才真正落到了请求行为上。