Go ResponseController Hijack 怎样判断连接是否支持接管

在 Go 的 HTTP Handler 中需要接管底层连接时，优先使用 http.NewResponseController(w).Hijack()，并把“不支持接管”当成正常能力分支处理。默认的 HTTP/1.x ResponseWriter 支持 Hijack，HTTP/2 则明确不支持；中间件包装过的 ResponseWriter 也可能隐藏这项能力。成功接管后，HTTP 服务端不再管理这条连接，应用代码必须自己负责后续读写、超时和关闭。

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

先把 Hijack 的支持范围说清楚

ResponseController 是对原始 http.ResponseWriter 能力的统一访问入口。创建控制器时应传入 Handler 收到的原始 ResponseWriter，或者传入能够通过 Unwrap 找回原始对象的包装器。控制器发现底层没有对应方法时，会返回匹配 http.ErrNotSupported 的错误。

因此，不能用“当前服务监听的是某个端口”推断一定能接管，也不建议把 Hijack 失败当成程序异常直接让 Handler 继续写原响应。判断点应该放在实际调用结果上。

用 ResponseController 调用 Hijack

下面的 Handler 只演示能力判断和资源交接。它没有实现完整的 WebSocket 或自定义协议，接管成功后只写入一段原始连接数据，重点是看清返回值和责任变化。

package main

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

func hijackHandler(w http.ResponseWriter, r *http.Request) {
    // ResponseController 会沿着包装器的 Unwrap 查找底层能力。
    controller := http.NewResponseController(w)

    // Hijack 成功后，HTTP server 不再管理这条连接。
    conn, readWriter, err := controller.Hijack()
    if err != nil {
        // ErrNotSupported 代表当前协议或包装器没有接管能力。
        if errors.Is(err, http.ErrNotSupported) {
            http.Error(w, "当前连接不支持 Hijack", http.StatusNotImplemented)
            return
        }
        // 其他错误也要结束当前分支，避免继续使用不确定的连接状态。
        http.Error(w, "连接接管失败", http.StatusInternalServerError)
        log.Printf("hijack failed: %v", err)
        return
    }

    // 接管后由业务代码负责释放 net.Conn，不能再依赖 HTTP server 清理。
    defer conn.Close()

    // bufio.ReadWriter 可能保留客户端已经发送但尚未被处理的数据。
    if _, err := fmt.Fprintln(readWriter, "raw connection accepted"); err != nil {
        log.Printf("write raw response failed: %v", err)
        return
    }
    // Flush 把缓冲区中的数据交给底层连接。
    if err := readWriter.Flush(); err != nil {
        log.Printf("flush raw response failed: %v", err)
    }
}

func main() {
    // 通过独立路径暴露示例 Handler，实际项目应按协议和鉴权要求限制入口。
    http.HandleFunc("/hijack", hijackHandler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

这里的关键不是返回了一行文本，而是 Hijack 同时交付了 net.Conn 和 *bufio.ReadWriter。后者可能包含已经从客户端读入的未处理数据，不能简单丢弃；如果业务协议需要继续解析，应先消费这部分缓冲内容。

不支持时怎样安全降级

当错误匹配 http.ErrNotSupported 时，最常见原因是 HTTP/2 或 ResponseWriter 包装器没有转发 Hijacker 能力。此时应在尚未接管前返回一个普通 HTTP 状态，并结束 Handler。不要先调用 w.WriteHeader、再尝试 Hijack，也不要在 Hijack 失败后继续假设已经拿到了连接。

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

func tryHijack(w http.ResponseWriter) (net.Conn, bool) {
    // 这里用能力探测函数集中处理降级，调用方只关心是否获得连接。
    controller := http.NewResponseController(w)
    conn, _, err := controller.Hijack()
    if err != nil {
        // ErrNotSupported 是能力不匹配，不应被包装成无条件重试。
        if errors.Is(err, http.ErrNotSupported) {
            return nil, false
        }
        // 其他错误也不返回半初始化资源给上层。
        return nil, false
    }
    return conn, true
}

如果项目需要在 HTTP/2 下实现双向流，不要把 Hijack 当成通用方案。HTTP/2 连接不提供这条接口，应改用仍然遵守 HTTP/2 语义的流式响应、升级协议或专用库；文章中的判断只解决“当前 ResponseWriter 是否允许接管”这一问题。

接管后最容易漏掉的三个边界

• 连接关闭：成功接管后，HTTP server 不再负责这条连接，应用必须在所有路径关闭 net.Conn。
• 请求体失效：官方文档明确要求 Hijack 后不要继续使用原始 Request.Body；后续输入应从返回的缓冲读写器或连接读取。
• 请求上下文时机：Handler 返回前，原 Request 的 Context 仍然有效；如果后台 goroutine 继续使用连接，必须自行设计生命周期，不能把 Handler 返回后的 Context 当成连接存活保证。

一张清单判断是否适合使用

一句话总结：ResponseController.Hijack 的正确用法不是“强行拿到底层连接”，而是“调用一次、按 error 判断能力、成功后完整接管资源、失败时回到普通 HTTP”。只要把 HTTP/2 不支持、包装器能力和接管后清理这三层边界写进代码，连接接管就不会变成隐含的资源泄漏。

常见问题

为什么不能只对 ResponseWriter 做 Hijacker 类型断言？

类型断言可以工作，但 ResponseController 能处理包装器的 Unwrap，并把能力探测与其它响应控制方法统一起来。实际项目中使用控制器更容易保留中间件兼容性。

HTTP/2 下 Hijack 失败是代码写错了吗？

不一定。HTTP/2 的默认 ResponseWriter 有意不实现 Hijacker，返回 ErrNotSupported 是预期行为。应改用适合 HTTP/2 的流式或升级方案。

Hijack 成功后还能调用 w.Write 吗？

不应继续把原 ResponseWriter 当作普通 HTTP 响应出口。接管后由返回的 net.Conn 和 bufio.ReadWriter 负责后续协议数据。