Go ResponseController SetWriteDeadline 返回错误时怎么判断

ResponseController.SetWriteDeadline 返回错误时，先用 errors.Is(err, http.ErrNotSupported) 判断响应对象是否支持这项能力；不匹配时保留原始错误，按底层实现排查。设置成功也只表示该调用没有报告错误，后面的 Write、Flush 仍要分别处理，不能把这三个位置的失败都归为“写超时”。

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

影响面：增加中间件后，设置截止时间突然失败

考虑一个示例场景：处理器原本能设置响应截止时间，加入记录状态码的中间件后，设置操作报错，但普通短响应仍然能写出。这不矛盾。中间件可能保留了基础 ResponseWriter 接口，却遮住了可选能力。这个场景用于解释定位方法，不是线上事故实录。

排查时先记录错误来自哪个调用，以及传给 NewResponseController 的对象类型。正文能写出只能说明基础写入路径可用，不能证明设置截止时间也可用。

定位顺序：先确认失败发生在哪里

同一个错误字符串出现在不同位置，处理策略可能完全不同。因此日志应带阶段字段；错误类型与响应包装类型也比仅记录一句“timeout”更有用。

根因：基础接口没有承诺截止时间能力

ResponseWriter 的基础方法是 Header、Write 和 WriteHeader，截止时间方法属于额外能力。ResponseController 会检查当前对象是否实现对应方法；没有时，可经由 Unwrap() http.ResponseWriter 继续寻找底层响应对象。包装器直接实现了目标方法时，该方法的结果优先，不会因为它返回错误就自动绕过去调用底层。

这解释了两种不同情况：包装器没有暴露解包入口时，底层能力可能被挡住；底层本身不支持时，单纯添加 Unwrap 也不会创造能力。测试替身只有基础写入能力时，同样不能假设它能设置截止时间。

修复动作：将设置、写入、刷新分开记录

下面是包内处理器示例，适用于提供 ResponseController 的 Go 版本。本例把截止时间能力视为必要条件：不支持时在正常响应开始前返回服务不可用。若业务允许降级，可以改为继续处理，但必须承认响应未受这次设置保护。

package reply

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

// wrappedWriter 保留基础接口，并暴露实际包装的响应对象。
type wrappedWriter struct {
    http.ResponseWriter
}

func (w *wrappedWriter) Unwrap() http.ResponseWriter {
    return w.ResponseWriter
}

func Handler(w http.ResponseWriter, r *http.Request) {
    rc := http.NewResponseController(w)
    err := rc.SetWriteDeadline(time.Now().Add(4 * time.Second))
    if err != nil {
        if errors.Is(err, http.ErrNotSupported) {
            // 本例要求截止时间能力；不支持时拒绝进入正常响应逻辑。
            log.Printf("stage=set_write_deadline kind=unsupported writer=%T", w)
            http.Error(w, "response capability unavailable", http.StatusServiceUnavailable)
            return
        }
        // 保留设置阶段与错误类型，避免把任何错误都记成超时。
        log.Printf("stage=set_write_deadline type=%T err=%v", err, err)
        return
    }

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    if _, err := io.WriteString(w, "ready\n"); err != nil {
        // 写入错误与设置错误单独记录；此时不再追加错误响应正文。
        log.Printf("stage=write type=%T err=%v", err, err)
        return
    }
    if err := rc.Flush(); err != nil {
        // Flush 是另一种能力，不能因设置截止时间成功就省略错误处理。
        log.Printf("stage=flush type=%T err=%v", err, err)
    }
}

示例中的 wrappedWriter 只展示解包形式，实际中间件还应保留自己的状态记录逻辑。不要为修复截止时间问题而更换成另一份 ResponseWriter，更不要让 Unwrap 返回自己形成循环。处理器直接收到包装后的 w 时，将它传给 NewResponseController 即可。

判断不支持应使用 errors.Is，而不是 err == http.ErrNotSupported 或字符串比较。控制器返回的错误可以匹配该哨兵，但不必与它直接相等。其余错误是被调用方法的结果，具体含义应结合对象实现和调用阶段判断。

防复发：绝对截止时间不是每次写入自动续期

time.Now().Add 得到的是绝对时刻，不是每次 Write 都重新计算的空闲超时。若流式响应确实需要刷新预算，应在原截止时间尚未过期时依据业务策略设置，而不是等失败后才尝试“复活”。官方文档明确说明，写截止时间过期后再设置并不能延长它。

超过截止时间的正文写入不会阻塞，但如果数据进入了缓冲，仍可能成功。因此不能以一次小块 Write 的 nil 返回证明客户端收到全部数据。Flush 也应单独看错误；它不等于客户端业务层确认。零值 time.Time 表示不设置截止时间，不是“立即超时”。

ResponseController 只能在 ServeHTTP 尚未返回时使用。写截止时间也不会自动停止处理器里的 CPU 计算或其他业务任务；那些工作应另按各自取消机制管理。

Flush 成功，SetWriteDeadline 就一定支持吗？

不一定。控制器按不同方法分别寻找能力，某个方法可用不代表其他方法也可用。

添加 Unwrap 后仍报不支持怎么办？

继续检查真实底层对象及中间每一层；也要看是否存在直接实现目标方法、却返回不支持错误的包装层。

设置返回 nil，为什么后来仍然写失败？

设置结果和后续 I/O 结果是不同事件。截止时间到期、连接状态变化或其他底层错误，都需要在实际写入位置记录。

参考：ResponseController 官方契约；标准库能力查找与错误包装实现。