Go HTTP Header 写入后再修改为什么客户端看不到

在 Go 的 HTTP handler 里，w.Header().Set() 只是修改服务端手里的响应头映射；真正让客户端看到它，要等响应头被提交。普通响应一旦调用了 WriteHeader，或者第一次调用 Write 触发隐式的 200 OK，后面再改普通 header 就不会追溯到已经提交的响应。

把状态码、Content-Type、鉴权结果和自定义响应头都放在第一次 WriteHeader/Write 之前决定。若分支还可能失败，就先完成判断，再统一写头和写响应体。

一、为什么 Header 写了却消失

ResponseWriter.Header() 返回的是当前响应的 header map。它适合在响应尚未提交时设置字段，但不是一个“客户端实时同步”的对象。服务器准备发送响应头时，会把这个 map 的内容用于构造响应；构造完成后，普通 header 的修改就失去了发送机会。

最容易忽略的触发点是 Write：

func wrong(w http.ResponseWriter, r *http.Request) {
	// 第一次 Write 会隐式提交 200 和当前已有的响应头。
	_, _ = io.WriteString(w, "ok")

	// 这里改的是服务端 map，客户端已经收不到这个普通响应头。
	w.Header().Set("X-Trace-Mode", "late")
}

如果用 curl -i 或浏览器开发者工具查看，通常只能看到第一次写入前已经存在的字段。这个现象不是客户端缓存，也不是 Header().Set 偶尔失效，而是响应提交点已经越过。

二、WriteHeader 和 Write 谁先把响应定型

两种写法都可能成为提交点。显式调用 WriteHeader(status) 时，状态码和当时的普通响应头一起进入响应；如果没有显式调用，第一次 Write 会先按 http.StatusOK 提交，再写入正文。

因此，下面这种顺序也会让状态码判断失效：

func wrongStatus(w http.ResponseWriter, r *http.Request) {
	// 这里已经把响应固定成 200。
	_, _ = io.WriteString(w, "checking")

	// 这个 500 不会替换已经提交的状态；问题应在写正文前返回。
	if r.URL.Query().Get("fail") == "1" {
		w.WriteHeader(http.StatusInternalServerError)
	}
}

一个 handler 最好只保留清晰的最终提交责任：成功分支写成功头和正文，错误分支调用 http.Error 后立即 return。不要在写出部分正文后再试图改变状态码或普通响应头。

三、把所有分支判断放在响应提交之前

更稳妥的接口设计是先收集请求信息、校验参数、调用业务层，再根据结果选择状态码和头部。下面的示例把“能否成功”和“客户端需要看到什么”放在同一个提交点前处理：

func detail(w http.ResponseWriter, r *http.Request) {
	// 先处理方法和参数，避免提交后才发现错误。
	if r.Method != http.MethodGet {
		w.Header().Set("Allow", http.MethodGet)
		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
		return
	}
	if r.URL.Query().Get("id") == "" {
		http.Error(w, "missing id", http.StatusBadRequest)
		return
	}

	// 成功分支的普通响应头必须在 WriteHeader 前设置。
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.Header().Set("X-Trace-Mode", "detail")
	w.WriteHeader(http.StatusOK)

	// 提交之后只写正文，不再修改普通响应头或状态码。
	_, _ = io.WriteString(w, `{"ok":true}`)
}

这里的关键不是强行显式调用 WriteHeader(200)，而是让提交时机可见、不可误解。如果成功响应没有额外状态码，也可以只设置头后直接 Write；但团队约定若要返回非 200，必须先设置所有头，再显式提交状态码。

排查时可以沿着三处看：谁第一次调用了 Write，谁第一次调用了 WriteHeader，以及 http.Error 是否已经替你提交了错误响应。很多中间件会提前写状态或正文，遇到“业务 handler 明明 Set 了 header 但客户端没有”的问题，还要检查中间件是否先结束了响应。

四、常见问题

调用两次 WriteHeader，后一次会覆盖前一次吗？

对最终的 2xx–5xx 响应，通常只有第一次提交的状态生效；后一次不能把已经发送的最终状态改掉。把每个错误分支写成“响应后立即 return”更容易维护。

WriteHeader 后还能设置 trailer 吗？

可以，但要使用 HTTP trailer 语义：提前声明 Trailer 字段，或者按标准支持的 trailer 方式写入。普通 header 和 trailer 不是同一个发送阶段，不能把任意字段当成 trailer 来补救。

为什么某些 Header 看起来不用设置也会出现？

Write 可能自动补充 Content-Type，小响应也可能自动生成 Content-Length；这些自动行为不改变“普通自定义 header 必须在提交前设置”的规则。

记住一个判断句就够了：客户端看不到的 header，先不要盯着客户端，回到 handler 中寻找第一个 WriteHeader 或 Write，再把需要发送的字段移到它之前。