ResponseWriter 在 HTTP/2 下为什么不能直接 Hijack

在 Go 的 net/http 服务里，HTTP/2 请求拿不到 http.Hijacker 不是接口失效，而是有意设计的协议边界：HTTP/1.x 的默认 ResponseWriter 可以在满足条件时接管整条连接，HTTP/2 则不会支持连接级 Hijack。HTTP/2 一条 TCP 连接承载多个相互独立的流，如果某个请求把整条连接变成原始字节流，其他流就无法继续由 HTTP/2 帧层管理。

官方资料：https://pkg.go.dev/net/http

先判断业务到底需要“原始连接”还是“持续推送/双向交互”。前者只适合明确的 HTTP/1.x 路径；后者在 HTTP/2 下应继续使用流级 API 或协议级方案，不要强行把 ResponseWriter 转成 net.Conn。

• HTTP/2 下默认 ResponseWriter 不实现 http.Hijacker，ResponseController.Hijack 也会返回不支持错误。
• ResponseWriter 包装器在任何协议下都可能隐藏底层能力，能力判断要放在运行时。
• 只想让数据尽快发出时，使用 Flush；只想感知客户端断开时，使用 Request.Context。
• 业务确实依赖自定义字节协议时，应让入口明确协商适合的协议，而不是在 HTTP/2 流中绕过帧层。

HTTP/2 的连接和 ResponseWriter 到底差在哪里

HTTP/1.1 的一个请求通常对应一条由服务器管理的连接上下文，Hijack 的语义是把这条连接的后续读写责任交给处理器。接管后，HTTP 服务器不再替处理器解析请求或写响应，调用方需要管理返回的 net.Conn、缓冲读写器、超时和关闭动作。

HTTP/2 把请求拆成流，并在同一条连接上复用多个流。ResponseWriter 表面上仍然提供 Header、Write 和 Flush，但它写入的是当前流对应的 HTTP/2 帧，不是可以任意读取和写入的裸 TCP 字节。把一条共享连接交给单个处理器，会破坏其他请求的帧调度，因此 Go 的 HTTP/2 实现故意不提供 Hijacker。

先按协议版本和能力判断，不要盲目调用 Hijack

排查时可以先看 r.ProtoMajor，再检查当前包装后的 ResponseWriter 是否实现了 http.Hijacker。协议版本只能说明请求来自 HTTP/1.x 还是 HTTP/2，不能替代能力检查，因为中间件包装器也可能不暴露 Hijacker。

package main

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

func handle(w http.ResponseWriter, r *http.Request) {
    // 协议版本只用于选择方向，不把它当成能力保证。
    fmt.Printf("request protocol: %s\n", r.Proto)
    if r.ProtoMajor == 2 {
        http.Error(w, "HTTP/2 请求不能做连接级 Hijack", http.StatusNotImplemented)
        return
    }

    // 包装器可能隐藏 Hijacker，先做运行时能力判断。
    if _, ok := w.(http.Hijacker); !ok {
        http.Error(w, "当前 ResponseWriter 不支持 Hijack", http.StatusNotImplemented)
        return
    }

    // 只有确定要接管时才调用；Hijack 不是无副作用的探测函数。
    controller := http.NewResponseController(w)
    conn, rw, err := controller.Hijack()
    if err != nil {
        // ResponseController 会把不支持的能力报告为 ErrNotSupported。
        if errors.Is(err, http.ErrNotSupported) {
            http.Error(w, "底层实现拒绝连接接管", http.StatusNotImplemented)
            return
        }
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    // 接管后由当前处理器负责关闭连接和管理缓冲读写器。
    defer conn.Close()
    _, _ = rw.WriteString("raw connection mode\n")
    _ = rw.Flush()
}

这里有一个容易忽略的点：不能为了“探测是否支持”就直接调用 Hijack。成功调用会改变连接的所有权，后面的普通 HTTP 响应流程已经不能再按原方式继续。真正的探测可以使用类型断言；真正接管时再调用 ResponseController.Hijack 并处理错误。

HTTP/1.1 需要原始连接时，Hijack 要负责什么

如果业务是自定义 TCP 对话、旧式 WebSocket 入口或必须自行编排后续字节的协议，先让路由或入口明确使用 HTTP/1.x，再进入 Hijack 分支。接管成功后，HTTP 服务器不会替你继续写响应，返回的缓冲读写器里还可能有客户端已经发送但尚未消费的数据。

实际代码至少要处理三件事：保存并使用返回的缓冲读写器、根据协议需要设置或清除读写截止时间、在所有路径关闭连接。若业务仍需要读取原始请求体，也不能在 Hijack 之后继续使用原来的 Request.Body。

func rawProtocol(w http.ResponseWriter, r *http.Request) {
    // 只有明确选择 HTTP/1.x 原始协议时才进入此分支。
    if r.ProtoMajor != 1 {
        http.Error(w, "raw protocol requires HTTP/1.x", http.StatusHTTPVersionNotSupported)
        return
    }

    hj, ok := w.(http.Hijacker)
    if !ok {
        http.Error(w, "hijacker is unavailable", http.StatusNotImplemented)
        return
    }
    conn, rw, err := hj.Hijack()
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    // 从这里开始由业务接管生命周期，必须确保连接最终关闭。
    defer conn.Close()

    // 先写协议握手，再刷新缓冲区让对端尽快收到数据。
    if _, err := rw.WriteString("CUSTOM/1.0 101 Switching Protocols\\r\\n\\r\\n"); err != nil {
        return
    }
    if err := rw.Flush(); err != nil {
        return
    }
    // 后续读取、超时和协议帧解析都属于自定义协议的责任。
}

如果前面有压缩、鉴权或日志中间件，别假设它们把原始 ResponseWriter 原样传下来了。对这类路径，最好在集成测试里同时覆盖“支持 Hijack”“包装器不支持”和“请求被取消”三种结果。

HTTP/2 下用流级 API 完成推送和取消

很多“想 Hijack”的真实需求其实只是希望长时间输出、边计算边发送，或者在客户端离开后停止后台工作。这些需求不要求拿到 TCP 连接，可以保持 HTTP/2 的流语义。

func stream(w http.ResponseWriter, r *http.Request) {
    controller := http.NewResponseController(w)
    ticker := time.NewTicker(500 * time.Millisecond)
    defer ticker.Stop()

    for i := 1; i 

上面的代码需要导入 fmt、net/http 和 time。ResponseController.Flush 会在底层支持时刷新响应；如果包装器不支持该能力，应把错误当成当前响应无法继续流式发送处理，而不是退回到裸连接。

如果处理器需要在读取请求体的同时写响应，HTTP/1 请求可以按需调用 EnableFullDuplex；Go 的 HTTP/2 服务本身允许并发读取请求和写响应。这个能力解决的是读写并行，不等于允许 Hijack。

按业务目标选择替代方案

如果业务必须使用 WebSocket 或其他升级协议，应该从协议实现和入口协商的角度确认 HTTP 版本、代理链和库能力。不要把“协议级升级”和“任意连接 Hijack”混为一谈：前者仍然有明确的握手和帧语义，后者是把连接生命周期直接交给处理器。

常见问题

为什么 HTTP/1.1 可以 Hijack，HTTP/2 不可以？

因为 HTTP/2 的一条连接承载多个流，单个处理器接管整条连接会影响其他流。Go 官方文档明确说明，HTTP/1.x 默认 ResponseWriter 支持 Hijacker，而 HTTP/2 连接有意不支持。

ResponseController.Hijack 能不能绕过 HTTP/2 限制？

不能。ResponseController 只是把可选能力统一到一个入口；底层不支持时会返回匹配 http.ErrNotSupported 的错误，它不会把流级 ResponseWriter 变成裸连接。

只想让响应更快到达客户端，该调用什么？

优先使用 ResponseController.Flush 或经过运行时判断的 http.Flusher。它们刷新当前响应流，不改变连接所有权，适合 HTTP/2 的事件流和进度输出。

如何判断是 HTTP/2 还是中间件包装器导致不支持？

先记录 r.Proto，再做 http.Hijacker 类型断言。HTTP/2 下默认实现不支持；HTTP/1.x 下仍可能因为包装器没有转发接口而不支持，这时要检查中间件是否提供正确的 Unwrap 或保留原始 ResponseWriter。

小结

“ResponseWriter 在 HTTP/2 下不能直接 Hijack”本质上是连接级 API 与流级协议模型不匹配。需要原始连接时，把路径限定在明确的 HTTP/1.x 场景并承担完整生命周期；需要推送、取消或双向交互时，优先使用 Flush、Request.Context 和协议级实现。这样既能保留 HTTP/2 的多路复用，也能让代码在代理和中间件变化后更容易排查。