Go net/http.ResponseController 怎样判断输入是否满足边界

判断 net/http.ResponseController 的输入是否满足边界，首先看 ResponseWriter 是否来自当前 Handler，包装器能否通过 Unwrap 返回真实底层 Writer，以及操作是否发生在 ServeHTTP 返回之前。控制器创建成功不等于底层支持所有操作；执行具体方法时，仍要区分匹配 http.ErrNotSupported 的能力错误与其他错误。

我会把“来源和生命周期”作为首要约定，再写按操作划分的降级分支，不会用一次类型断言代替所有能力判断。下面的原创示例发送两段简短报告，主动刷新只是可选能力；它不虚构线上故障，也没有实测延迟结论。

官方接口：https://pkg.go.dev/net/http#NewResponseController

引入版本说明：https://go.dev/doc/go1.20

1. 变化一句话：统一控制入口，能力仍来自底层

Go 1.20 引入 ResponseController，将刷新、连接接管及读写期限等控制操作放到一个入口。后续新增的方法各有自己的版本要求，不能把所有方法都当作 Go 1.20 就存在。本文只使用该版本已有的构造器和 Flush。

它不是新的网络连接，也不会替任意 Writer 生成缺失能力。一个只实现 Header、Write、WriteHeader 的自定义响应对象，并不因此获得读写期限或连接接管功能。判断必须落到当前要用的那个操作。

2. 为什么要看 Writer 来源与包装链

官方要求传入的 Writer 是 ServeHTTP 收到的原始值，或者由提供 Unwrap 的包装器返回原始 Writer。中间件若只嵌入 ResponseWriter 而没表达解包关系，可选能力可能被遮住。每层包装都应该清楚知道自己代理的是谁，避免返回自身、nil 或形成循环。

Unwrap 也不是万能补丁。如果包装器自己缓存、压缩或转换响应，直接向下层 Flush 可能没有处理外层缓存。此时需要包装器设计与自身语义一致的刷新行为，而不只是机械加一个解包方法。本文选择完全透传的包装器，特意不引入这类额外缓存。

nil 接口或内部持有 nil 指针的伪 Writer 不是有效响应对象。一次 w != nil 并不能证明实现正确；更可靠的方式是让 Writer 只从 Handler 参数进入，避免接受任意对象作为生产响应输入。构造器没有返回 error，不代表它替你验证了全部合同。

3. 对旧代码的影响：能力探测与真实操作不能混同

旧代码可能写成“断言为 Flusher，成功就 Flush”。迁移后可以用控制器表达操作并处理 error，但不能把 Flush 当作纯查询。它会推进响应发送，可能提交原本尚未提交的响应头。因此，应在确实准备发送内容时调用，而不是在一切业务检查之前随手探测。

如果“不支持某能力”意味着业务不能继续，应该在提交正常响应前设计可接受的判断或拒绝方案。本文中刷新可有可无，所以允许普通响应降级；这个选择不能原样复制到必须实时分段交付的产品合同里。

4. 迁移建议：把降级条件写在调用旁边

将以下程序保存为 main.go，使用 Go 1.20 或以上版本。它只监听本机地址，提供 /report 的 GET 响应。这里给出可集成代码，本文未启动服务器或运行请求。

package main

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

type passWriter struct {
    http.ResponseWriter
}

func (w *passWriter) Unwrap() http.ResponseWriter {
    // 本包装器不缓存或转换正文，返回实际底层 Writer。
    return w.ResponseWriter
}

func report(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodGet {
        w.Header().Set("Allow", http.MethodGet)
        http.Error(w, "只接受GET", http.StatusMethodNotAllowed)
        return
    }
    wrapped := &passWriter{ResponseWriter: w}
    controller := http.NewResponseController(wrapped)
    wrapped.Header().Set("Content-Type", "text/plain; charset=utf-8")
    if _, err := fmt.Fprintln(wrapped, "报告摘要"); err != nil {
        log.Printf("写摘要失败: %v", err)
        return
    }

    // 此时确实准备发送摘要，Flush 不是无副作用的能力探测。
    if err := controller.Flush(); err != nil {
        if errors.Is(err, http.ErrNotSupported) {
            log.Print("不支持主动刷新，继续普通响应")
        } else {
            // 正文可能已发送，不能再改成另一份HTTP错误响应。
            log.Printf("刷新失败: %v", err)
            return
        }
    }
    if _, err := fmt.Fprintln(wrapped, "报告结束"); err != nil {
        log.Printf("写结尾失败: %v", err)
    }
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/report", report)
    server := &http.Server{
        Addr:              "127.0.0.1:8080",
        Handler:           mux,
        ReadHeaderTimeout: 5 * time.Second,
    }
    // 仅供本地集成示例，不在包外保存控制器或响应Writer。
    log.Fatal(server.ListenAndServe())
}

errors.Is 用于匹配 ErrNotSupported，不比较错误文本，也不要求返回错误与哨兵值直接相等。其他刷新错误直接记录并结束处理。因为前一段正文可能已经提交，不能再调用 http.Error，假装能够把原来的成功响应完整替换成500。

示例没有在 Handler 结束后启动 goroutine 继续写入，也不把控制器存进全局变量。日志只记录错误类别和原因，实际业务可补充请求关联标识，但不应该把用户正文或密钥写进去。

若改用 SetWriteDeadline，还要理解它是写期限控制，不是业务计算的硬超时。期限经过后再设置时间不能保证恢复已经超时的写入；一些写入也可能因数据仍在缓冲而成功。不要把“设置成功”写成“接下来所有计算和网络传输必定在指定时长内完成”。

5. 最小检查设计：看实际包装组合，不凭协议名推断

接入自己的中间件时，应覆盖原始 Writer、透传且正确 Unwrap 的包装器、遮蔽能力的包装器，以及返回 ErrNotSupported 和其他错误的实现。要观察能力错误分支是否仍交付普通报告，以及真实写入错误发生后是否停止后续操作。本文提供检查设计，没有运行这些检查。

对固定示例而言，方法为GET时应尝试写摘要、执行刷新并按结果决定是否写结尾；其他请求方法应收到405及Allow头。这些是代码推导的预期，不是实际HTTP回执。透传链最终是否支持刷新，取决于真实Writer，不能用一份只保存响应正文的测试对象证明网络刷新能力。

一个操作成功，其他操作也一定支持吗？

不一定。刷新、读写期限和连接接管分别有各自的能力要求。不要把 Flush 的结果缓存成一个笼统的“控制器可用”标志。

为什么加了 Unwrap 还是不能及时看到内容？

还要看外层是否有缓存，以及代理和客户端如何处理数据。控制器解决的是响应控制调用入口，不提供跨所有网络层的展示确认。

可以在后台任务里保留控制器吗？

不能在 ServeHTTP 返回后继续使用。需要长时间处理时，先重新设计请求与任务的交付方式，明确响应的拥有者和生命周期。

输入边界最后应写成什么规则？

只接收当前Handler的真实Writer，包装关系真实且有限，按操作返回值决定降级或失败，并在Handler内结束所有控制调用。这个合同比构造前做一个表面非空判断更有用。