Go ResponseController 穿不过中间件：Unwrap 与可选能力透传
处理器没有改，外面加了一层统计响应字节的中间件，ResponseController.SetWriteDeadline 却开始返回“不支持”。先别调整超时数值，底层连接可能根本没有收到这次设置：包装器只暴露了 http.ResponseWriter 的三个基本方法，把其他能力藏起来了。
Go 1.24.1 的 ResponseController 可以通过包装器的 Unwrap() http.ResponseWriter 继续向内寻找能力。这个约定让中间件不必手工重写所有可选接口，但前提是它真的返回当前响应对应的下层writer。
下面先验证能力查找，再讨论它与真正的网络截止时间有什么区别。
一层看似透明的嵌入，仍然会改变方法集合
结构体嵌入一个 http.ResponseWriter 接口，只会通过这个接口暴露的方法获得转发。运行时装进去的对象还有SetWriteDeadline或Flush，不代表外层自动拥有这些方法。
保存为 main.go：
package main
import (
"errors"
"fmt"
"net/http"
"net/http/httptest"
"time"
)
type deadlineWriter struct {
*httptest.ResponseRecorder
deadline time.Time
}
func (writer *deadlineWriter) SetWriteDeadline(value time.Time) error {
writer.deadline = value
return nil
}
type opaqueWrapper struct {
http.ResponseWriter
}
type transparentWrapper struct {
http.ResponseWriter
}
func (writer *transparentWrapper) Unwrap() http.ResponseWriter {
return writer.ResponseWriter
}
func main() {
requested := time.Date(2030, 1, 1, 0, 0, 0, 0, time.UTC)
base := &deadlineWriter{ResponseRecorder: httptest.NewRecorder()}
hidden := &opaqueWrapper{ResponseWriter: base}
err := http.NewResponseController(hidden).SetWriteDeadline(requested)
if !errors.Is(err, http.ErrNotSupported) {
panic(fmt.Sprintf("unexpected opaque result: %v", err))
}
if !base.deadline.IsZero() {
panic("opaque wrapper unexpectedly reached base")
}
fmt.Println("opaque wrapper: write deadline capability hidden")
visible := &transparentWrapper{ResponseWriter: base}
if err := http.NewResponseController(visible).SetWriteDeadline(requested); err != nil {
panic(err)
}
if !base.deadline.Equal(requested) {
panic("requested deadline did not reach base")
}
if err := http.NewResponseController(visible).Flush(); err != nil {
panic(err)
}
if !base.Flushed {
panic("flush did not reach recorder")
}
fmt.Println("Unwrap wrapper: deadline and flush reached base")
unsupported := &transparentWrapper{
ResponseWriter: httptest.NewRecorder(),
}
err = http.NewResponseController(unsupported).SetWriteDeadline(requested)
if !errors.Is(err, http.ErrNotSupported) {
panic("recorder unexpectedly supports network deadline")
}
fmt.Println("Unwrap cannot invent an unsupported base capability")
}
运行 go run main.go。第一条说明能力被隐藏；第二条说明通过Unwrap找到底层方法；第三条说明真正的底层不支持时，继续解包也不会凭空产生能力。
deadlineWriter 只是可观测的测试对象，记录收到的时间，没有真正的网络连接。这个程序验证的是接口透传，不是“截止时间在网络上生效”的实验。把方法被调用与底层I/O真的超时分开，测试结论才不会越界。
截止时间传入的是绝对时间点，不是持续时长。调用点负责构造它，包装器透传时不应擅自重新计算一份完整预算。
Unwrap 是继续查找的入口，不是更换响应对象
多层中间件可以各自返回下一层，控制器沿链查找，直到找到对应能力或到达无法继续的对象。漏掉中间任何一层，就可能让更深层的能力无法被发现。
返回自己会让查找无法前进，返回另一个请求的writer则直接破坏响应归属。包装器应在创建时绑定本次请求的下层对象，不能为了复用分配把同一个实例无保护地交给多个并发请求。
普通Write、WriteHeader、Header仍然由中间件按自己合同转发。Unwrap并不自动替你统计字节、修正默认状态或实现压缩，只是给控制能力提供一条可靠路径。
如果外层对正文做了缓冲，底层Flush成功也不代表外层缓冲已经写出去。包装器若拥有需要先刷新的状态，就应实现合适的刷新方法，先处理自己这一层，再向下转发。否则“控制器找到底层”与“调用者收到需要的流式效果”仍然可能不同。
同理，压缩层可能需要把压缩缓冲同步推出去。透明解包只解决方法发现，不能自动理解每层数据变换。中间件是否适合透传某种控制，仍由它自己的实现决定。
这个Unwrap方法与错误链的Unwrap也只是名字相同。错误链约定返回error，响应包装链约定返回http.ResponseWriter，不能把包装器交给errors.Unwrap来完成能力发现。类型签名才是协议的一部分，仅有一个同名函数并不足够。
如果中间件在Write中增加计数，应按底层实际返回的n记录，而不是直接加len(data)后忽略短写和错误。虽然这不改变Unwrap查找，错误的统计仍会让“写出了多少”与客户端可能收到的数据不符。能力透传和统计准确要分别验证，不能靠其中一个测试通过替代另一个。
使用控制器时，错误必须参与选择
SetWriteDeadline返回错误，说明调用方不能按“已经设置成功”继续假设后续行为。若这项控制是接口正确性的必要条件，可以在写响应前拒绝或改走受支持路径；若只是优化，则应保留可观测诊断，并遵守其他已有预算。
不要捕获所有错误后统一当成“不支持”。底层方法也可能返回其他真实错误，调用者需要保留它们的含义。示例只对确定的能力缺失使用errors.Is检查，没有用字符串包含“supported”来猜错误类型。
ResponseController 还提供设置读取截止时间、劫持连接等控制入口，但每项能力的支持范围不同。找到Flush，不说明就一定能Hijack；HTTP协议和底层实现也会影响可用性。给一个封装写“支持ResponseController”太宽，应该验证自己实际依赖的方法。
控制器不能在处理器返回后继续随意使用。响应生命周期已经交还给服务器，再从后台goroutine对同一writer调截止时间或写正文，会脱离原来的请求管理。需要长连接或流式处理时，应让处理器作用域持续拥有它，或者采用明确的连接接管协议。
把中间件回归测在最终组合上
单独测试最外层包装器，可能发现不了第二层日志或第三层压缩隐藏了能力。服务真正部署的是组合链，因此测试应按实际顺序装配，再对需要的控制入口做验证。
httptest.ResponseRecorder 本身支持一些观测行为，但不是拥有真实连接的writer。不能因为它的网络截止时间方法不支持，就推断生产Server也不支持；同样不能用测试替身记录了一次调用，宣称真实慢客户端已经被超时终止。
先用本例固定包装协议，再补真实本地服务与客户端的I/O测试。若前一类失败，查方法集合和Unwrap；若前一类通过、后一类不符合预期，才继续查协议、缓冲、截止时间选择和实际读写时点。两种测试回答不同问题，排障路径也就不必混在一起。
