Go HTTP 服务怎样安全切换到原始连接

Go 的 net/http 处理器如果需要从 HTTP 层切换到原始 TCP 连接，应该先做能力检查，再调用 Hijack。安全的关键不是“强制断言成功”，而是确认当前 ResponseWriter 支持 http.Hijacker，成功移交后只使用返回的连接和缓冲读写器，并由业务代码负责期限与关闭。

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

这个能力适合少数需要自定义连接协议的场景。HTTP/1.x 的默认响应写入器通常支持它；HTTP/2 连接明确不支持，响应写入器包装器也可能不再暴露该接口，所以不能凭运行环境猜测。

先把“能不能接管”判断清楚

不要把 ResponseWriter 直接转换成具体实现类型。接口断言既能适配标准库，也能让不支持接管的服务器或包装器走降级路径：

func rawConnHandler(w http.ResponseWriter, r *http.Request) {
	// 先检查能力，失败时连接仍由 HTTP 服务端管理。
	hj, ok := w.(http.Hijacker)
	if !ok {
		http.Error(w, "当前连接不支持原始连接接管", http.StatusNotImplemented)
		return
	}

	// 只有拿到接口后才请求资源移交。
	conn, rw, err := hj.Hijack()
	if err != nil {
		http.Error(w, "接管连接失败", http.StatusInternalServerError)
		return
	}
	defer conn.Close() // 接管成功后，关闭责任转移到当前处理器。

	_ = rw
	_ = r // 接管后不再读取 r.Body。
}

这里的错误码只是一个明确的降级示例，实际项目可以根据协议协商结果返回自定义响应。重要的是：能力检查失败时不要继续调用 Hijack，否则会把不支持的协议或包装器当成实现细节处理。

Hijack 成功后，哪些资源归谁管理

Hijack 返回 net.Conn 和 *bufio.ReadWriter。调用成功后，HTTP 服务端不会再替你管理这条连接；处理器应只围绕这两个返回值进行原始协议读写。返回的读缓冲中可能已经有客户端发来的未处理数据，不能假设它一定为空。

func serveRaw(conn net.Conn, rw *bufio.ReadWriter) error {
	// 先设置一个有限期限，防止对端长期占用连接。
	if err := conn.SetDeadline(time.Now().Add(30 * time.Second)); err != nil {
		return err
	}

	// 通过缓冲写入器发送协议前导，并显式刷新到连接。
	if _, err := rw.WriteString("RAW/1 READY\n"); err != nil {
		return err
	}
	if err := rw.Flush(); err != nil {
		return err
	}

	// 读取已经进入缓冲区的数据，避免绕过 bufio.Reader 丢失字节。
	line, err := rw.ReadString('\n')
	if err != nil {
		return err
	}
	_ = line
	return nil
}

接管后原始 Request.Body 不应继续使用；请求上下文在 ServeHTTP 返回前仍然有效，但它不会替代连接本身的关闭责任。若协议需要长连接，可在完成握手后清除或重新设置期限，并确保每个错误返回路径都能关闭连接。

从一个最小原始协议入口开始

把能力判断、资源接收和协议处理拆开，后续更容易替换为 WebSocket 前置握手、代理隧道或自定义文本协议。处理器只负责 HTTP 到原始连接的边界，连接函数负责期限、读写和退出。

func hijackEndpoint(w http.ResponseWriter, r *http.Request) {
	// ResponseController 适合统一访问底层能力，但仍要处理错误。
	controller := http.NewResponseController(w)
	conn, rw, err := controller.Hijack()
	if err != nil {
		http.Error(w, "当前请求无法切换协议", http.StatusNotImplemented)
		return
	}
	defer conn.Close() // 无论协议处理成功或失败，都释放连接。

	if err := serveRaw(conn, rw); err != nil {
		log.Printf("原始协议结束: %v", err)
	}
	_ = r // 仅保留请求元数据时使用 r，不再读取 Body。
}

ResponseController.Hijack 是较新的统一入口，语义仍然遵循 Hijacker 的能力边界；如果项目需要兼容不同实现，错误处理依旧不能省略。对 HTTP/2 请求，应准备不使用原始接管的替代协议路径。

发布前的责任清单

一句话总结：先确认能力，再接管；接管之后，HTTP 框架的连接管理就结束了，缓冲、期限和关闭都必须由你的协议处理代码明确负责。

常见问题

为什么 HTTP/2 请求不能照搬 Hijacker 代码？

因为标准库默认的 HTTP/2 响应写入器不支持该接口。应改用协议本身支持的流式能力，或在连接协商阶段选择 HTTP/1.x 路径。

Hijack 后还能继续调用 ResponseWriter.Write 吗？

不应继续。连接已经移交给处理器，后续应通过返回的连接或缓冲读写器通信。