Go ResponseController 设置写超时的适用边界

http.ResponseController.SetWriteDeadline 适合在某个处理器内部，为当前响应写入设置更具体的绝对截止时间。它尤其适用于 SSE、分块输出或其他长时间响应：服务端可以在每次准备写数据前更新截止时间，避免一个迟迟不读取的客户端长期占住写操作。

它不是“整个请求最多执行多久”的开关，也不会自动取消业务计算、返回 504 或绕过反向代理超时。截止时间一旦已经超过，再设置新的时间也不能把它延长；写入在过期后不会继续阻塞，但数据若仍在缓冲区内，调用也可能暂时看起来成功。

先判断它解决什么问题

Server.WriteTimeout 是服务器级配置，对处理器不能按路由做精细决策。某些普通 API 希望整体限制较短，而事件流或大文件响应需要更长的存活时间。此时可以让全局配置负责常规连接，再在特定处理器内用 SetWriteDeadline 管理下一次写入允许等待到什么时刻。

这里的参数是一个 time.Time，代表绝对时间，不是持续时长。传入零值表示不设置写截止时间。若目标是“每个数据块最多等待 5 秒”，就应在每个数据块写出前计算 time.Now().Add(5 * time.Second)，而不是只在处理器开始时设置一次。

理解 ResponseController 的控制边界

http.NewResponseController(w) 不会创建新的网络连接。它从当前 ResponseWriter 开始查找 SetWriteDeadline(time.Time) error 能力；遇到包装器时，会通过包装器的 Unwrap() http.ResponseWriter 继续寻找原始写入器。最终实现若支持该方法，截止时间会作用到底层响应写入。

如果整条包装链都没有这项能力，控制器会返回一个可用 errors.Is(err, http.ErrNotSupported) 识别的错误。控制器只能在 ServeHTTP 返回前使用，不能保存起来交给后台 goroutine 在请求结束后继续操作。

在流式处理器里滚动设置截止时间

下面示例先用零值测试写截止时间能力，再在每个事件写出前滚动设置 5 秒截止时间。Flush 也通过同一个控制器调用并检查错误，这样更容易暴露缓冲写入之后的真实发送问题。

package main

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

func streamEvents(w http.ResponseWriter, r *http.Request) {
	ctl := http.NewResponseController(w)

	// 零值表示不设截止时间，同时确认包装链是否支持该能力。
	if err := ctl.SetWriteDeadline(time.Time{}); err != nil {
		if errors.Is(err, http.ErrNotSupported) {
			http.Error(w, "当前响应写入器不支持写截止时间", http.StatusInternalServerError)
			return
		}
		http.Error(w, "无法配置写截止时间", http.StatusInternalServerError)
		return
	}
	defer ctl.SetWriteDeadline(time.Time{}) // 处理器返回前清除本次设置。

	w.Header().Set("Content-Type", "text/event-stream")
	w.Header().Set("Cache-Control", "no-cache")

	ticker := time.NewTicker(time.Second)
	defer ticker.Stop()

	for seq := 1; seq 

滚动设置适合表达“单次写入不能长时间卡住”。如果你只在函数开头设置一次，那么它表达的是一个固定的总写入边界。两种含义都可能合理，但必须在设计时选清楚。

中间件包装要保留 Unwrap

日志、指标和压缩中间件常用自定义类型包装 http.ResponseWriter。如果包装器只转发 Header、Write 和 WriteHeader，控制器看不到底层扩展能力，就会返回 ErrNotSupported。最小修正是提供 Unwrap。

type statusWriter struct {
	http.ResponseWriter
	status int
}

func (w *statusWriter) WriteHeader(code int) {
	w.status = code // 记录状态码后继续交给底层写入器。
	w.ResponseWriter.WriteHeader(code)
}

func (w *statusWriter) Unwrap() http.ResponseWriter {
	return w.ResponseWriter // 让 ResponseController 继续发现底层能力。
}

若包装器本身改变了缓冲或写入语义，仅实现 Unwrap 还不等于自动安全。它只负责暴露底层能力；你仍要确认包装层的缓冲策略是否会让数据晚于预期才真正写到连接。

不要混淆四种超时

处理超时后的边界状态

第一，过期后的写调用不会继续阻塞，但官方文档明确指出：如果数据只写进了缓冲区，它仍可能返回成功。因此流式响应要同时检查 Write 和 Flush，不要只看格式化写入的返回值。

第二，截止时间已经超过后，再设置未来时间不能把它延长。滚动更新必须发生在旧截止时间到期之前；一旦确认超时，就结束当前处理器，不要试图原地恢复同一个响应。

第三，截止时间不是状态码。响应头已经发送后，通常也无法再改成结构化的 5xx 响应。正确做法是记录超时类型、停止生成后续数据并释放资源。若需要向客户端保证完整结果，应该改用可重试的分段下载、任务查询或游标接口，而不是依赖一条无限长响应。

常见问题

普通 JSON API 要给每个处理器都加 ResponseController 吗？

通常不需要。先用 http.Server 的服务器级超时建立默认边界，再把控制器留给确实需要不同写入策略的路由。

设置 5 秒截止时间是否表示处理器 5 秒后一定退出？

不表示。它约束响应写入，不会停止 CPU 计算或数据库查询。处理器自身仍要监听 Context，并为下游调用配置对应超时。

为什么 SetWriteDeadline 返回 ErrNotSupported？

常见原因是自定义 ResponseWriter 没有实现该能力，也没有提供 Unwrap。先修复包装链，再决定不支持时是降级、拒绝流式响应还是改用服务器级配置。