ResponseController 怎样接管全双工 HTTP 连接

ResponseController 接管“全双工”的正确方式，是在 Handler 第一次写响应之前调用 EnableFullDuplex()。它会告诉 Go 的 HTTP/1 服务器：不要为了写响应而先把尚未读取的请求体全部消费掉，允许 Handler 继续读取 Request.Body，同时向 ResponseWriter 写数据。

这里的“接管”不是 Hijack。应用仍在 net/http 的 HTTP 语义内工作，不会拿到裸 net.Conn，也不需要自己解析帧。HTTP/2 服务端本来就允许请求读取与响应写入并行；这个开关主要解决 HTTP/1 的默认行为。

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

先确认场景真的需要全双工

大部分 API 都不需要调用它。先把交互模型分清：

真正适合它的是第三类：客户端不准备先结束上传，却又要等服务器的中间反馈再继续。如果 HTTP/1 Handler 在请求体未读完时直接写响应，服务器的默认预消费行为可能与客户端的等待策略互相卡住。

在首次响应写入前启用能力

控制器必须基于 Handler 收到的原始 ResponseWriter 创建，或者包装器要提供 Unwrap() http.ResponseWriter。随后在 WriteHeader、Write 或 Flush 之前调用 EnableFullDuplex，并检查错误：

rc := http.NewResponseController(w)
if err := rc.EnableFullDuplex(); err != nil {
    // 包装器不暴露底层 writer 时，可能得到 ErrNotSupported。
    if errors.Is(err, http.ErrNotSupported) {
        http.Error(w, "当前响应链不支持全双工", http.StatusNotImplemented)
        return
    }
    http.Error(w, "无法启用全双工", http.StatusInternalServerError)
    return
}

// 成功启用后再设置响应头和开始输出。
w.Header().Set("Content-Type", "application/x-ndjson; charset=utf-8")

如果中间件自定义了 ResponseWriter，却既不实现全双工能力，也不提供 Unwrap，控制器无法到达底层实现。不要忽略这个错误，否则 HTTP/1 下仍会沿用默认行为。

建立逐块读取与逐块确认的处理阶段

下面的 Handler 接收逐行数据，每读到一行就回写一条 JSON 确认并 Flush。示例把输入上限、上下文取消和输出错误放在同一个可退出循环里：

func duplexHandler(w http.ResponseWriter, r *http.Request) {
    // 限制请求体，避免长连接把无限输入留给服务端。
    r.Body = http.MaxBytesReader(w, r.Body, 1

这段代码并不要求读写各占一个 goroutine。单个 Handler 循环“读一块、写一块”已经属于交错读写，也更容易保证只有一个执行路径操作 ResponseWriter。

为读写两侧设置独立门禁

全双工连接寿命长，必须把资源边界写清楚。EnableFullDuplex 只改变读写协作方式，不会自动带来输入上限、超时、取消传播或刷新策略。

• 输入大小：用 MaxBytesReader 限制总请求体，并给 Scanner 或解码器设置单条记录上限。
• 请求取消：循环与上游工作都应观察 r.Context()。
• 读写超时：按协议需要调用 SetReadDeadline 与 SetWriteDeadline，并分别处理错误。
• 输出刷新：每次 Write 后检查 Flush，不要把进入 Go 缓冲区误当成客户端已收到。
• 写入所有权：若确实拆成多个 goroutine，集中到一个写协程，避免并发操作 ResponseWriter。

协议与中间件边界要分开处理

HTTP/1 与 HTTP/2 的差异

官方文档说明，HTTP/1 服务器默认先消费未读请求体，再开始写响应；EnableFullDuplex 会关闭这个行为。HTTP/2 服务端本来就允许请求读取与响应写入并行，因此无需靠该开关改变协议能力。不过 ResponseWriter 文档也提醒，并非所有 HTTP/2 客户端都支持这类使用方式；能先读完再写时，仍应优先采用更兼容的普通模型。

EnableFullDuplex 与 Hijack 不同

Hijack 会把底层连接和缓冲读写器交给应用，之后由应用负责连接生命周期。EnableFullDuplex 没有这一步：请求、响应头、传输编码、Context 和连接关闭仍由 net/http 管理。需要 HTTP 语义内的双向流时用前者；只有确实要脱离 HTTP 服务器控制时才考虑后者。

代理可能继续缓冲

即使 Handler 每次都成功 Flush，反向代理或客户端仍可能缓冲响应。这个现象不代表 EnableFullDuplex 失败。验收环境必须包含真实链路，并明确代理是否支持请求上传与响应下载同时转发。

失败处理与观测回路

把每次连接看成一条独立工作流，至少记录下面几类结果：

1. 启用全双工是否成功，是否命中 ErrNotSupported。
2. 请求协议版本、读取记录数和已确认记录数。
3. 退出原因是 EOF、请求取消、读取错误、写入错误还是 Flush 错误。
4. 是否经过 ResponseWriter 包装器，以及包装器是否实现 Unwrap。
5. 客户端与代理是否真正支持上传和下载并行传输。

如果客户端上传一半后等待确认，而服务端直到请求体结束才有输出，先检查 EnableFullDuplex 是否在首次写入前成功调用；如果 Go 侧 Flush 成功但客户端不可见，再转向代理缓冲与客户端读取策略。

常见问题

调用 EnableFullDuplex 后必须启动两个 goroutine 吗？

不必须。单 goroutine 交错读取和写入更容易控制 ResponseWriter 的写入所有权；只有业务确实需要同时处理时才拆分，并做好同步与取消。

它能替代 WebSocket 吗？

不能直接等同。它仍然工作在普通 HTTP 请求与响应语义内，适合有限的双向流场景；是否选择 WebSocket、HTTP/2 流或其他协议，应由客户端、代理和消息模型共同决定。

为什么中间件之后返回 ErrNotSupported？

常见原因是自定义 ResponseWriter 隐藏了底层实现。让包装器提供 Unwrap() http.ResponseWriter，或把需要控制响应的逻辑放到不会破坏能力链的位置。

什么时候不该使用全双工？

当请求可以先完整读取、客户端或代理不支持双向流、业务没有中间反馈需求时，普通请求后响应更简单，也更容易兼容和运维。

最终判断很简单：只有协议确实要求“请求体还没结束，响应就必须开始”时，才让 ResponseController 启用全双工；启用之后仍要补齐输入上限、取消、截止时间、Flush、包装器能力和真实链路兼容性。