Go http.ResponseController 怎样在处理器中读取连接 hijack 能力

在 Go 的 HTTP 处理器里，如果确实需要从标准 ResponseWriter 退回到底层连接，推荐先用 http.NewResponseController(w) 读取 Hijack 能力。调用成功后，处理器拿到的是 net.Conn 和可能带有客户端剩余数据的 bufio.ReadWriter；HTTP/2 或不透明的响应写入器通常会返回 http.ErrNotSupported，这时应走普通 HTTP 降级路径。

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

先确定 Hijack 的适用边界

ResponseController 是处理器和底层响应能力之间的适配层。它接收原始的 http.ResponseWriter，也能沿着包装器的 Unwrap 方法寻找原始写入器；如果目标写入器提供 Hijack() (net.Conn, *bufio.ReadWriter, error)，控制器就可以转发这项能力。

这项能力不是“任何 HTTP 请求都能拿到 TCP 连接”。默认的 HTTP/1.x 服务端写入器支持 Hijack，但 HTTP/2 有意不支持；自定义 ResponseWriter 包装器如果既没有实现 Hijack，也没有正确提供 Unwrap，同样会得到 ErrNotSupported。所以代码应判断能力结果，而不是只根据请求 URL 或部署环境猜测。

在处理器中读取连接与缓冲区

最小调用只需要把当前写入器交给控制器，再处理两个返回对象。下面的代码展示的是接管边界：如果不支持，就发送普通错误；如果成功，后续读写使用返回的缓冲读写器，并把关闭责任绑定到当前处理器生命周期。

package main

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

func hijackHandler(w http.ResponseWriter, r *http.Request) {
    controller := http.NewResponseController(w)

    // Hijack 只在处理器仍处于 ServeHTTP 生命周期内调用。
    conn, bufrw, err := controller.Hijack()
    if err != nil {
        // 不支持时保留普通 HTTP 响应，不把能力差异变成服务崩溃。
        if errors.Is(err, http.ErrNotSupported) {
            http.Error(w, "当前连接不支持 hijack", http.StatusNotImplemented)
            return
        }
        http.Error(w, fmt.Sprintf("接管连接失败：%v", err), http.StatusInternalServerError)
        return
    }

    // 接管后连接由当前处理器负责关闭，不能再交给 HTTP 服务器管理。
    defer conn.Close()

    // 缓冲读写器可能保留客户端已经发送但尚未消费的数据。
    if _, err := bufrw.WriteString("连接已接管\r\n"); err != nil {
        return
    }
    // Flush 把缓冲内容交给底层连接；实际协议格式仍由业务自行负责。
    _ = bufrw.Flush()
}

这里有三个容易遗漏的边界。第一，Hijack 成功后，HTTP 服务器不会再对这条连接做后续管理；第二，返回的 bufio.ReadWriter 里可能已有客户端数据，不能直接丢弃；第三，官方文档明确提醒原始 Request.Body 在接管后不能继续使用，若确实要读数据，应使用接管后的连接或缓冲区。

处理失败降级与资源责任

在通用处理器中，最稳妥的策略是先把“能力不存在”和“接管动作失败”分开记录，但对客户端都返回明确的 HTTP 结果。ErrNotSupported 说明当前写入器无法提供这项能力，不等于服务器程序损坏；超时、底层连接错误或包装器自身错误，则应保留错误上下文，交给日志和上层重试策略处理。

不要在成功调用 Hijack 后继续调用 w.WriteHeader、w.Write 或依赖 HTTP 服务器自动刷新。连接已经脱离标准响应流程，协议头、分隔符、读取超时和关闭时机都变成接管代码的责任。接管成功之前，才可以用 http.Error 发送普通 HTTP 响应。

把接管动作放进可控入口

如果接管连接只是为了实现升级协议，建议把它限制在明确的路径和协议协商结果中，避免普通接口意外失去 HTTP 语义。若服务前面还有代理或自定义 ResponseWriter，启动时可以确认包装器是否透传 Unwrap 与 Hijack；真正处理请求时仍以 Hijack 的返回值为准。

• 不要强制断言 http.Hijacker。控制器的好处就是让包装层有机会通过 Unwrap 暴露能力，直接断言会绕开这层适配。
• 不要把 HTTP/2 当成可降级的同一条连接。它没有传统 HTTP/1.x 的 Hijack 语义，应改用适合 HTTP/2 的数据通道或保持普通响应。
• 不要把关闭责任留给服务器。接管后将 defer conn.Close() 放在成功分支内，并根据协议需要设置读写截止时间。
• 不要继续读取原始请求体。接管动作之后，使用返回的缓冲区和连接处理协议数据。

相关问题

ResponseController.Hijack 什么时候会返回 ErrNotSupported？

当当前 ResponseWriter 及其可解包的原始写入器都没有提供 Hijack 能力时会返回与 http.ErrNotSupported 匹配的错误，HTTP/2 是典型场景。

Hijack 成功后还能继续写 HTTP 响应吗？

不应继续依赖 ResponseWriter 的 HTTP 写入流程。接管后由调用方通过返回的连接或缓冲读写器负责后续协议字节、刷新、超时和关闭。

为什么要保留 Hijack 返回的 bufio.ReadWriter？

它可能包含客户端已经发送、但 HTTP 服务器尚未消费的缓冲数据；直接改用裸连接可能跳过这些数据，造成协议解析不完整。