Go HTTP 中间件重复写响应头的定位方法

Go 服务出现 http: superfluous response.WriteHeader call 时，真正的问题不是“第二个状态码为什么没生效”，而是同一条请求链里已经有人提交了响应，后续代码仍在继续写。定位要分两步：先找到首次提交点，再找到第二次调用 WriteHeader 的组件。最常见根因是中间件写出 401、403 或 500 后忘记 return，于是业务 Handler 又写了一次 200。

从用户看到的异常开始还原

重复写响应头往往同时出现三个信号：

• 服务端日志提示 superfluous response.WriteHeader call from ...，并给出第二次调用的位置。
• 客户端拿到的是第一次提交的状态码，后写入的状态码没有覆盖它。
• 响应体可能被拼接，例如先出现“unauthorized”，后面又跟着业务 JSON。

先用请求 ID 把访问日志、错误日志和业务日志关联起来。不要只搜索 WriteHeader：Write、json.Encoder.Encode、fmt.Fprint 和 http.Error 都可能间接提交响应。

先认清响应提交边界

http.ResponseWriter 的规则很明确：如果尚未显式调用 WriteHeader，第一次 Write 会隐式执行 WriteHeader(http.StatusOK)。对普通 2xx 到 5xx 响应，一条请求最终只能提交一次状态头。首次提交后，再修改普通响应头通常不会影响已发送结果。

因此下面这段代码看起来只显式写了一次状态码，实际已经重复提交：JSON 编码先触发了隐式 200，后面的 201 已经太晚。

func createOrder(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")

	// Encode 最终会调用 Write，因此这里隐式提交 200
	_ = json.NewEncoder(w).Encode(map[string]string{"id": "A1024"})

	// 此时再写 201 不会替换已经提交的 200
	w.WriteHeader(http.StatusCreated)
}

正确顺序是先设置 Header，再写状态码，最后写响应体：

func createOrder(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")

	// 在任何响应体写入之前确定最终状态码
	w.WriteHeader(http.StatusCreated)

	// 状态已提交，后续只写这一份响应体
	if err := json.NewEncoder(w).Encode(map[string]string{"id": "A1024"}); err != nil {
		// 响应已经提交，这里只记录传输错误，不能再改写成 500
		log.Printf("encode response: %v", err)
	}
}

沿中间件链找第二个响应拥有者

中间件不是各自拥有一份响应，它们共享同一个 ResponseWriter。某一层决定拦截请求并写出错误响应后，这条分支就应结束。下面的认证中间件正是典型问题：

func requireToken(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if r.Header.Get("Authorization") == "" {
			// http.Error 会写状态码和响应体，响应已经提交
			http.Error(w, "missing token", http.StatusUnauthorized)
			// 缺少 return，下面仍会进入业务 Handler
		}

		next.ServeHTTP(w, r)
	})
}

修复不是吞掉日志，而是明确响应所有权：认证层拒绝请求时，它就是该分支唯一的响应拥有者；业务 Handler 不应再运行。

func requireToken(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if r.Header.Get("Authorization") == "" {
			// 写出 401 后立刻结束当前请求分支
			http.Error(w, "missing token", http.StatusUnauthorized)
			return
		}

		// 只有认证通过时，响应所有权才交给后续 Handler
		next.ServeHTTP(w, r)
	})
}

定位顺序：从第二次写入反查第一次提交

标准库日志里的文件和行号通常指向第二次 WriteHeader。按这个位置向上检查当前分支，再向外检查中间件，重点寻找：

1. http.Error 后没有 return。
2. 中间件调用 next.ServeHTTP 后，又统一写一个状态码或 JSON 包装体。
3. 恢复中间件在下游已经写出部分响应后捕获 panic，再尝试写 500。
4. 日志或指标中间件为了记录状态，错误地调用了底层 WriteHeader 两次。
5. 业务函数先写响应，随后又把错误返回给上层，上层再写一次错误响应。

建议给每个分支画一条很短的“响应所有权线”：谁决定状态码，谁写响应体，写完是否立刻返回。只要一条线上出现两个拥有者，问题通常就清楚了。

临时加入提交探针，记录第一次和第二次调用

调用链复杂、日志只能看到第二次写入时，可以临时包装 ResponseWriter。探针记录首个最终状态码，并在再次调用 WriteHeader 时打印调用栈。它只用于普通 HTTP 接口定位；流式响应、WebSocket、HTTP Hijack 或依赖额外可选接口的端点，不应直接套用这个简化包装器。

type commitProbe struct {
	http.ResponseWriter
	committed bool
	status    int
}

func (p *commitProbe) WriteHeader(code int) {
	if p.committed {
		// 临时输出第二次提交的完整调用栈，定位后应移除探针
		log.Printf("duplicate WriteHeader: first=%d second=%d\n%s", p.status, code, debug.Stack())
		return
	}

	// 记录第一个最终状态码，再交给真实 ResponseWriter
	p.committed = true
	p.status = code
	p.ResponseWriter.WriteHeader(code)
}

func (p *commitProbe) Write(body []byte) (int, error) {
	if !p.committed {
		// 第一次写响应体等价于隐式提交 200
		p.committed = true
		p.status = http.StatusOK
	}
	return p.ResponseWriter.Write(body)
}

func (p *commitProbe) Unwrap() http.ResponseWriter {
	// 允许 ResponseController 继续找到原始 ResponseWriter
	return p.ResponseWriter
}

func traceCommit(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		probe := &commitProbe{ResponseWriter: w}
		next.ServeHTTP(probe, r)
	})
}

探针应放在尽量靠外的位置，这样认证、限流、恢复和业务 Handler 都经过同一个包装器。日志收集到调用栈后，回到业务代码修复所有权，不要把“忽略第二次调用”当成永久方案。

组件实现：让状态码只有一个出口

复杂服务可以让下层函数只返回数据和错误，由最外层 HTTP Handler 统一编码响应。这样中间件只负责“放行或拦截”，业务函数不直接接触 ResponseWriter，重复写头的机会会明显减少。

func orderEndpoint(w http.ResponseWriter, r *http.Request) {
	order, err := loadOrder(r.Context(), r.PathValue("id"))
	if err != nil {
		// 当前分支只写一次错误响应，然后立即返回
		http.Error(w, "order not found", http.StatusNotFound)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	// 成功分支不必显式写 200，首次 Encode 会自动提交 200
	if err := json.NewEncoder(w).Encode(order); err != nil {
		log.Printf("encode order: %v", err)
	}
}

如果必须在下游写响应，就约定“写过响应的函数不再把可响应错误返回给上层”。错误值、布尔值或专用结果类型都可以，关键是让调用者知道响应是否已经提交。

用测试固定拒绝与成功分支

修复后至少测试两条路径：缺少凭据时业务 Handler 不能被调用；认证通过时只返回业务状态。测试不需要依赖服务端日志，只要验证调用次数、状态码和响应体即可。

func TestRequireTokenStopsAfterUnauthorized(t *testing.T) {
	called := 0
	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// 如果认证中间件正确 return，这里永远不会执行
		called++
		w.WriteHeader(http.StatusOK)
	})

	req := httptest.NewRequest(http.MethodGet, "/orders/A1024", nil)
	rec := httptest.NewRecorder()
	requireToken(next).ServeHTTP(rec, req)

	// 同时验证响应结果和下游调用次数，避免只修日志不修控制流
	if rec.Code != http.StatusUnauthorized {
		t.Fatalf("status=%d, want=%d", rec.Code, http.StatusUnauthorized)
	}
	if called != 0 {
		t.Fatalf("next called %d times, want 0", called)
	}
}

边界状态与排查清单

• 第一次 Write 是否已经隐式提交 200？
• http.Error、JSON 编码或模板渲染后是否立即结束分支？
• 中间件在 next.ServeHTTP 之后是否还会写状态码或响应体？
• 恢复中间件是否试图把已经部分发送的响应改成 500？
• 临时 ResponseWriter 包装器是否影响 Flusher、Hijacker 等可选接口？
• 测试是否同时断言状态码、下游调用次数和响应体，而不是只看日志？

最终原则很简单：一个请求分支只能有一个最终响应拥有者。日志指出第二次写入者，控制流分析帮助找到第一次提交者；把二者放回同一条中间件链，就能快速定位真正缺失的 return 或多余的统一响应包装。

参考资料：Go 官方 net/http.ResponseWriter 与 Handler 文档，以及标准库 net/http/server.go 的重复写头日志实现。