、标点随便，你们看着爽就行。

一、 先摆烂——最常见的错误示例

说实话... 下面这段代码是典型的“我爱乱开goroutine，然后把ResponseWriter往外丢”的坑：

func main {
    http.HandleFunc {
        fmt.Println
        // ✅ 同步写入响应
        w.WriteHeader
        _, _ = w.Write)
        // ✅ 异步任务：启动 goroutine，但绝不操作 w！
        go func {
            // 比方说：记录访问日志到文件/数据库、发送监控指标等
            fmt.Printf
        }
    })
    fmt.Println
    http.ListenAndServe
}

看起来还行吧？可实际运行时 如果你在异步goroutine里再动手去写就会出现 “http: superfluous response.WriteHeader call from” 的错误，划水。。

⚠️ 注意事项：defer+recover 那点事儿

不忍直视。 很多人喜欢在handler里套一层defer func{...}来捕panic，然后在里面w.WriteHeader。但要知道， 这个defer不只在panic时跑，它一定会在函数结束时跑——也就是说即使没panic，也会再调一次WriteHeader！于是就出现了“多次调用”。示例：

defer func{
    data := recover
    error_str := "We encountered an internal error"
    if err, ok := data.; ok {
        error_str = err
    }
    fmt.Println
    w.WriteHeader // ← 这里可能是第二次调用
    w.Write)
}

如果你已经手动用了w.WriteHeader自动发200)，千万别在defer里再随便调。

二、官方说了算——WriteHeader 的使用规则

• 只能调一次！
• 必须在写body之前调！
• If you don’t call it yourself，第一次 Write 会自动发 200。
• If you call it twice ，服务器会直接打印 log 并且忽略后面的 header。

# 小技巧：自己检查是否已经写过 Header

AFAIK， ResponseWriter 接口本身没有暴露一个叫w.Written的方法， 破防了... 所以我们只能自己包一层：

type safeWriter struct {
    http.ResponseWriter
    wrote bool
}
func  WriteHeader {
    if sw.wrote {
        // 已经写过了就别管它，直接返回
        return
    }
    sw.wrote = true
    sw.ResponseWriter.WriteHeader
}
func  Write {
    if !sw.wrote {
        // 第一次 Write 自动发 200，这里帮忙标记一下
        sw.wrote = true
    }
    return sw.ResponseWriter.Write
}

用法就是把原来的.Wrap一下然后全站换成这个平安版。

三、 实战案例：从“报错”到“稳如老狗”

#1 基础版——只用同步代码

func handler {
   // 只要在这里一次性搞定，就不会出问题
   w.Header.Set
   w.WriteHeader      // 第一次也是唯一一次
   _, _ = w.Write)
   // 不要再开 goroutine 去动 w 啦~
}

#2 高级版——异步日志 + 平安 Writer

func handler {
   sw := &safeWriter{ResponseWriter:w}
   defer func{
       if rec := recover; rec != nil{
           // 不要
调 WriteHeader，这里直接用 sw 写入错误信息即可
           sw.Write))
       }
   }
   go func{
       // 日志记录专用，不碰 sw，也不碰原始 w
       log.Printf
   }
   sw.Header.Set
   sw.WriteHeader
   _, _ = sw.Write)
}

这样即使handler内部panic，也不会导致第二次WriteHeader， 结果你猜怎么着？ 主要原因是我们把所有真正的IO都锁死在safeWriter里。

四、 FAQ – 常见奇怪问答

# 为什么有时候我明明没调两遍，却还是报错？

躺平... - 主要原因是 net/http 在 handler 返回后会自动补发 200。如果你用了 goroutine 把响应推迟到 handler 已经结束，那它已经帮你发了 200；而你的 goroutine 再调一次就冲突了。解决办法：不要把任何和 ResponseWriter 有关的操作放到子协程里。

# 我想在 panic 后返回 500，该怎么做？

- 用 defer 包裹整个 handler，在里面先判断是否已经写过 Header。如果没有，就手动调一次；如果已经有了就直接 write 错误信息，不再调 Header，等着瞧。。

# 有没有办法让 WriteHeader “变成可重复”？

- 没有。HTTP 协议规定每个响应只能有一个状态码。如果硬要装逼， 可以自己实现一个 buffer，把所有内容先缓存起来然后统一 flush，一次性发送。但这基本等同于自己造轮子，没必要，我破防了。。

五、

• 不要跨 goroutine 使用同一个 w http.ResponseWriter
• If you call WriteHeader manually，一定记得别再 Call 一遍，包括 defer 那种隐式的。
• If you need async work， 务必把它们和响应分离——比如发送日志到 MQ、写 DB 等等。
• If you really想玩儿 “防止重复”，自己封装一个 safe writer 或者用第三方框架。
• The most important thing is: 把代码弄得像个小学生一样直接、 粗暴，但一定记住 “一次 Header，一次 Body”。否则日志里一直出现 http: superfluous response.WriteHeader call from ...

本文纯属个人经验分享，若有冒犯请见谅。祝大家玩 Go HTTP 顺顺利利，不要被那该死的 WriteHeader 给整疯！🤪🚀，有啥说啥...

我心态崩了。 © 2026 烂文作者 | 本站内容仅供学习交流， 请勿用于生产环境，否则后果自负。