Go ServeHTTP 里写 Header 后再改状态码为什么无效

在 Go 的 ServeHTTP 中，Header() 返回的是“待发送”的响应头 map，不是可以在响应发出后随时修改的对象。只要先调用了 WriteHeader，或者先写入了响应体，状态码和普通响应头就基本已经确定；后面再改，客户端自然看不到。

为什么 Header 写了却改不了状态码

ResponseWriter 的生命周期可以拆成两个概念：Header() 先提供待提交的字段，WriteHeader(code) 或第一次 Write 再提交状态和头部。官方接口说明明确指出，第一次 Write 会触发隐式 WriteHeader(http.StatusOK)。

所以这段代码最终通常还是 200，而不是 401：

func badHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "先写了一点内容") // 第一次 Write 隐式提交 200
    w.Header().Set("Content-Type", "application/json") // 普通头已错过提交时机
    w.WriteHeader(http.StatusUnauthorized) // 不能改写已经提交的状态
}

问题不在 Header().Set 语法，而在响应提交点已经发生。即使底层协议允许缓冲，也不要把缓冲当成可以回滚状态码的保证。

ServeHTTP 里正确的响应顺序

稳定的写法是：先读取请求并完成校验，接着设置所有普通响应头，然后显式提交状态码，最后写入响应体。成功响应也建议显式写出状态码，代码审查时更容易看出哪个分支负责提交响应。

func authHandler(w http.ResponseWriter, r *http.Request) {
    if r.Header.Get("Authorization") == "" {
        w.Header().Set("Content-Type", "application/json; charset=utf-8") // 先设置普通头
        w.WriteHeader(http.StatusUnauthorized) // 再提交错误状态
        _, _ = io.WriteString(w, `{"error":"missing authorization"}`) // 最后写正文
        return // 防止成功分支继续写入
    }

    w.Header().Set("Content-Type", "application/json; charset=utf-8") // 成功分支也先设头
    w.WriteHeader(http.StatusOK) // 明确提交 200
    _, _ = io.WriteString(w, `{"ok":true}`) // 写入成功正文
}

如果不需要区分成功状态，直接写体也可以，Go 会把状态默认为 200；但一旦有错误码、缓存控制或内容类型，先把判断做完再提交更稳妥。

错误分支如何避免重复提交

实际项目最容易出错的是错误分支没有结束函数。比如鉴权失败已经写了 401，函数却继续执行查询和成功返回，最终日志里会出现“重复 WriteHeader”提示，客户端仍只收到第一次确定的状态。

func replyJSON(w http.ResponseWriter, code int, body string) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8") // 统一普通头
    w.WriteHeader(code) // 每个调用点只提交一次最终状态
    _, _ = io.WriteString(w, body) // 忽略短响应中的写入错误由上层策略处理
}

func handler(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        replyJSON(w, http.StatusMethodNotAllowed, `{"error":"method not allowed"}`)
        return // 错误响应后必须结束当前处理
    }
    replyJSON(w, http.StatusCreated, `{"created":true}`) // 成功出口
}

中间件也要遵守同一规则：下游 handler 返回后，不要无条件再写状态或正文。若确实要追加响应头，先约定由哪一层拥有提交权，并保证追加发生在提交之前。

相关问题

不调用 WriteHeader 时状态码是什么？

只要写入响应体，首次 Write 会隐式提交 200；如果既没写头也没写体，处理器结束时通常也是一个空的成功响应。

重复调用 WriteHeader 会覆盖状态吗？

对 2xx–5xx 响应，最多只有一个最终状态，后面的调用不会把它改成新状态。应通过分支 return 保证只有一个提交点。

提交后还能修改 Header 吗？

普通响应头通常不能；1xx 响应和预先声明的 HTTP trailer 属于特殊机制，不能拿来修正已经发出的普通头或状态。

排查这类问题时，沿着 ServeHTTP 找第一个 Write、WriteHeader 或可能触发刷新的调用，再检查它之前是否已经完成状态判断，通常比盯着最后一次 Header().Set 更快。