Go http.ResponseController 如何判断连接能力：Flush、Hijack 与失败回退

做流式 HTTP 响应时，能不能刷新缓冲区、能不能接管底层连接，不应该靠猜 ResponseWriter 的具体类型。Go 的 http.ResponseController 可以从当前响应对象探测这些能力：支持就调用 Flush 或 Hijack，不支持时收到 ErrNotSupported，再走普通响应或明确报错的回退路径。

ResponseController 解决的是“当前 ResponseWriter 有没有这项能力”的探测问题，不会凭空给响应增加能力；ErrNotSupported 是能力边界，不应被当成网络故障重试。

先看一个流式响应的判断现场

一个导出接口会先写出几行进度，再在任务结束时返回结果。开发时最容易出现的写法是把 w.(http.Flusher) 当成所有场景的固定入口，或者直接假设 Hijack 一定可用。经过中间件包装、测试响应记录器或特殊协议适配后，ResponseWriter 的能力可能已经变化。

func stream(w http.ResponseWriter, r *http.Request) {
    controller := http.NewResponseController(w)
    if err := controller.Flush(); err != nil {
        if errors.Is(err, http.ErrNotSupported) {
            http.Error(w, "当前响应不支持流式刷新", http.StatusNotImplemented)
            return
        }
        http.Error(w, "刷新响应失败", http.StatusBadGateway)
        return
    }
    _, _ = io.WriteString(w, "data: ready\n\n")
}

这里先探测 Flush，再决定是否进入流式路径。要注意顺序：如果已经把大量普通正文写入缓冲区，失败后的状态码和错误正文未必还能按预期修改。

Flush 和 Hijack 解决的是两种不同的连接问题

Flush 仍然处于 HTTP 响应模型里，它只是请求当前响应链把已写内容向客户端推进。适合 SSE、进度输出和分段结果，但它不能保证客户端立刻渲染，也不能绕过代理缓冲。

Hijack 则是连接所有权的切换。调用成功后，调用方得到 net.Conn 和读写缓冲对象，后续协议处理不再由 net/http 的普通响应流程负责。它更像“离开 HTTP 服务端的默认轨道”，所以只在确实要接管连接时使用。

func takeOver(w http.ResponseWriter) (net.Conn, *bufio.ReadWriter, error) {
    controller := http.NewResponseController(w)
    conn, rw, err := controller.Hijack()
    if err != nil {
        if errors.Is(err, http.ErrNotSupported) {
            return nil, nil, fmt.Errorf("Hijack 不可用: %w", err)
        }
        return nil, nil, err
    }
    return conn, rw, nil
}

探测失败时不要把 ErrNotSupported 改写成“连接断开”。前者说明响应对象没有暴露所需能力，后者才是网络链路或对端行为问题。

为什么测试环境经常拿不到这两项能力

httptest.ResponseRecorder 主要记录状态码、响应头和响应体，它不是一个真实网络连接，也不会模拟连接劫持。用它测试普通 Handler 输出很合适，但用它断言 Hijack 成功就会把“测试替身不支持”误判成业务缺陷。

测试流式代码时，可以把能力探测封装在自己的小接口里，分别为支持和不支持两种分支提供测试替身；真正的连接接管测试则放在使用真实监听器的集成测试中。这样单元测试验证回退逻辑，集成测试验证连接状态变化，职责更清楚。

把错误分支写成可以验收的结果

1. 调用 Flush 前确认响应头已经写入必要的内容类型，例如 text/event-stream。
2. 收到 ErrNotSupported 时记录“能力不支持”，不要无条件重试同一个调用。
3. 调用 Hijack 成功后立即切换到 net.Conn 的读写流程，并关闭连接或交还连接的责任写进代码。
4. 测试中分别覆盖支持、ErrNotSupported 和真实网络错误三条路径，避免只验证成功样例。

如果只是想尽快把一段结果发出去，优先考虑 Flush；只有需要自定义协议或接管连接时才考虑 Hijack。这两个方法都不是“性能开关”，而是对当前响应链能力的明确询问。

相关问题

调用 Flush 后客户端一定马上看到内容吗？

不一定。服务端响应链、反向代理和客户端都可能继续缓冲。Flush 只能请求当前服务端把已有数据向下游推进，不能替代端到端的流式验收。

ErrNotSupported 要重试几次？

通常不需要重试。它表达的是当前 ResponseWriter 没有对应能力；除非你先切换到了不同的响应实现，否则重复调用仍会得到同样的边界结果。

Hijack 成功后还能继续写 ResponseWriter 吗？

不应继续。成功后连接控制权已经交给调用方，后续应使用返回的 net.Conn 和缓冲对象完成协议读写，并明确关闭责任。

把能力探测放在正确的分岔点

ResponseController 的价值在于把“响应对象支持什么”变成了可检查的调用链。先区分 Flush 的流式推进和 Hijack 的连接接管，再把 ErrNotSupported 与真实网络错误分开处理，代码就能在中间件、测试替身和真实监听器之间保持一致的边界。