直接替换 http.ResponseWriter 会丢失状态码和 Header，因其接口仅暴露 WriteHeader、Write 和 Header 方法，而底层实现依赖未导出字段；若包装结构体未同步维护 statusCode 等状态、未拦截 WriteHeader 调用并冻结 Header，则导致状态码被忽略、重复设置无效、Header 修改失效，JSON 包裹时易覆盖原始状态或违反 HTTP 协议。
为什么直接替换 http.ResponseWriter 会丢失状态码和 Header？
因为标准库的 http.ResponseWriter 接口只暴露了 WriteHeader、Write 和 Header 三个方法，但底层实现（比如 responseWriter）可能还依赖未导出字段（如已写入状态、缓冲区位置）。如果只是用结构体“包装”并透传调用，却没同步维护内部状态，就可能出现：状态码被忽略、重复调用 WriteHeader 无效果、Header 在 Write 后才设置却已发送。
关键点在于：必须拦截并记录 WriteHeader 调用，且在真正写入前确保 Header 已冻结；否则自定义格式化（如统一加 {"code":200,"data":...}）会覆盖原始状态或导致 HTTP 协议错误。
- 务必在包装结构体中保存
statusCode字段，并在首次WriteHeader时记录，后续调用应静默忽略（HTTP/1.1 不允许重写状态码） -
Header()返回的是引用，修改它本身没问题，但需注意：一旦Write或WriteHeader被调用，Header 就被视为“已发送”，再改无效 - 不要在包装体的
Write方法里直接调用w.Write()—— 应先判断是否已写 Header，未写则补上默认200 OK，再格式化内容
如何安全地包装 http.ResponseWriter 并支持 JSON 包裹？
最简可靠方式是嵌入原生响应器并实现接口，同时缓存写入内容。典型做法是用 bytes.Buffer 暂存 Write 数据，等全部写完再统一封装成 JSON 输出。
type JSONResponseWriter struct {
http.ResponseWriter
statusCode int
buf *bytes.Buffer
}
func (w *JSONResponseWriter) WriteHeader(statusCode int) {
w.statusCode = statusCode
w.ResponseWriter.WriteHeader(statusCode)
}
func (w *JSONResponseWriter) Write(b []byte) (int, error) {
if w.statusCode == 0 {
w.statusCode = http.StatusOK
w.ResponseWriter.WriteHeader(w.statusCode)
}
return w.buf.Write(b)
}
func (w *JSONResponseWriter) Flush() {
data := map[string]interface{}{
"code": w.statusCode,
"data": string(w.buf.Bytes()),
}
json.NewEncoder(w.ResponseWriter).Encode(data)
}
注意：Flush() 是手动触发最终输出的时机，通常放在 handler 结尾；若用在中间件中，需确保 handler 执行完毕后再调用。
立即学习“go语言免费学习笔记（深入）”；
- 不能把
buf放在Write里直接序列化 —— 因为Write可能被多次调用，而 JSON 只能写一次完整对象 - 如果 handler 中显式调用了
WriteHeader，你的包装体必须捕获它，否则Flush()里的code字段会错 - 对二进制响应（如图片、PDF）不适用 —— 这种包装天然只适合文本类响应，否则
string(w.buf.Bytes())会破坏数据
中间件中使用包装响应器时，为什么 http.StripPrefix 或 http.FileServer 会失效？
因为 http.FileServer 等内置处理器会直接检查 http.ResponseWriter 是否实现了额外接口（如 http.Pusher、http.Hijacker），而你的包装结构体若没显式实现这些接口，就会降级为基础行为，导致静态文件无法 push、WebSocket 升级失败等。
解决办法不是全量实现所有接口，而是按需委托：
func (w *JSONResponseWriter) Push(target string, opts *http.PushOptions) error {
if pusher, ok := w.ResponseWriter.(http.Pusher); ok {
return pusher.Push(target, opts)
}
return http.ErrNotSupported
}
func (w *JSONResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error) {
if hijacker, ok := w.ResponseWriter.(http.Hijacker); ok {
return hijacker.Hijack()
}
return nil, nil, http.ErrNotSupported
}
- 每次新增一个需要支持的接口，就得加一段类型断言 + 委托逻辑
- 若不确定下游是否用到某接口，宁可显式返回
http.ErrNotSupported，也不要 panic 或静默忽略 - 尤其注意
http.CloseNotify()已被弃用，新代码无需处理；但老项目若还在用，也要做兼容委托
什么时候不该用响应包装，而该改 handler 逻辑？
当你发现需要对不同路由返回不同结构（如 API 返回 {"data":...}，健康检查返回纯字符串 "ok"），硬套统一包装就会让健康检查也变成 {"code":200,"data":"ok"} —— 这反而破坏了约定。
更合理的方式是：只在明确需要统一格式的 handler 层做封装，而不是全局中间件。
- 对
/health这类简单端点，直接w.Write([]byte("ok"))，绕过包装体 - 对 REST API，用
json.NewEncoder(w).Encode(resp)显式构造，比依赖包装体更可控 - 若真要全局统一，建议用装饰器模式封装 handler 函数本身，而非响应器 —— 例如
func wrapHandler(h http.HandlerFunc) http.HandlerFunc，在写入前决定是否 JSON 包裹
响应包装器看似灵活，但容易掩盖业务语义；真正的边界在 handler 的职责划分，而不是在 ResponseWriter 上打补丁。
