Go ResponseWriter 写入状态码后为什么 Header 修改不生效

我排查 Go HTTP 接口时，最容易误判的一件事就是：明明调用了 w.Header().Set()，客户端却看不到新值。关键不在 Header 不能修改，而在响应头已经被提交了。对普通的 2xx–5xx 响应来说，WriteHeader 或第一次 Write 之后，再改普通 Header 通常不会影响已经发出的响应。

先看清 ResponseWriter 的提交时点

ResponseWriter 同时承担了“准备响应头”和“写响应体”两件事。Header() 返回的映射可以先写入内容；但一旦调用 WriteHeader，或者直接调用第一次 Write，服务器就会把状态和普通响应头视为已提交。此后再执行 w.Header().Set("X-Trace", "late")，内存里的映射可能还会变化，线上响应却不会跟着回写。

还有一个隐蔽的提交点：你没有写 WriteHeader，并不代表响应还没开始。下面的 Write 会先按 200 处理，再写正文：

func hello(w http.ResponseWriter, r *http.Request) {
    // 普通响应头要在第一次 Write 前准备好。
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")

    // 第一次 Write 会隐式提交 200 OK。
    _, _ = w.Write([]byte("ok"))

    // 这里再改普通 Header，对客户端已收到的响应没有作用。
    w.Header().Set("X-Trace", "late")
}

所以排查“Header 修改不生效”时，我先找这个 Handler 中最早的 WriteHeader、Write 或可能触发写入的封装函数，而不是继续尝试换大小写或重复调用 Set。

按分支组织响应，避免错误后再改头

接口通常有校验、失败和成功几条分支。比较稳的写法是：每条分支都在自己的响应契约里完成 Header、状态码和正文；错误响应结束后直接返回。这样既不会让成功分支覆盖错误状态，也不会在状态码已经提交后补改 Header。

func user(w http.ResponseWriter, r *http.Request) {
    // 先统一设置两条分支都需要的普通响应头。
    w.Header().Set("Content-Type", "application/json; charset=utf-8")

    if r.URL.Query().Get("id") == "" {
        // 状态码和正文一起完成，避免后续代码再次写响应。
        w.WriteHeader(http.StatusBadRequest)
        _, _ = w.Write([]byte(`{"error":"missing id"}`))
        return
    }

    // 成功分支在提交前补充自己的 Header。
    w.Header().Set("Cache-Control", "no-store")
    w.WriteHeader(http.StatusOK)
    _, _ = w.Write([]byte(`{"ok":true}`))
}

这里的顺序不是格式偏好，而是接口语义：Content-Type 和缓存策略属于普通 Header，必须在提交前决定；WriteHeader 只负责状态；Write 负责正文，并可能触发隐式 200。如果某个中间件或序列化辅助函数内部先写了正文，也要把它当成提交点处理。

普通 Header 不行时，看看是不是需要 Trailer

并非所有“写入之后设置 Header”都一定无效。Go 文档明确保留了两类边界：1xx 信息响应可以继续处理对应 Header；如果信息必须在响应体之后才产生，则应使用 HTTP Trailer，并提前声明 Trailer 名称，或者使用 http.TrailerPrefix 约定动态 trailer 键。

func stream(w http.ResponseWriter, r *http.Request) {
    // 先声明响应结束后才会出现的 Trailer 字段。
    w.Header().Set("Trailer", "X-Checksum")
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")

    // 先写正文；这一步会提交普通响应头。
    _, _ = w.Write([]byte("payload\n"))

    // Trailer 的值在响应结束阶段提供，不是普通 Header 回写。
    w.Header().Set("X-Checksum", "demo")
}

这个例子只说明 API 语义，实际流式响应还要结合传输协议和客户端能力确认 Trailer 是否能被正确读取。不要为了让普通 Header“晚点出现”而依赖重复 Set。

相关问题

调用两次 WriteHeader，后一次状态码会生效吗？

对最终的 2xx–5xx 响应，通常只有第一次提交的状态有效。应在分支判断完成后只选择一个最终状态。

只设置 Header 不调用 WriteHeader，会发送吗？

如果 Handler 最终没有写状态或正文，客户端未必能得到你期待的响应头；通常应让 Handler 完成一个明确的响应。

为什么 httptest 里看到的 Header 和线上不一样？

检查测试是否在写入之后读取或修改 Header，并区分 ResponseRecorder 的观察方式与真实服务器提交响应的时点。