在 Go Web 开发中，需先显式调用 WriteHeader() 设置状态码，再写入 JSON 响应体；若顺序颠倒或存在隐式写入，会导致状态码被强制覆盖为 200 并触发警告。
在 go web 开发中，需先显式调用 `writeheader()` 设置状态码，再写入 json 响应体；若顺序颠倒或存在隐式写入，会导致状态码被强制覆盖为 200 并触发警告。
Go 的 net/http 包对响应头和状态码的写入有严格时序要求：WriteHeader() 必须在任何响应体写入（包括 json.Encoder.Encode() 或 res.Write()）之前调用。这是因为 http.ResponseWriter.Write() 的底层实现会在首次写入响应体时自动设置状态码为 200 OK —— 且仅当状态码尚未设置时才生效。一旦状态码已被设定，后续再调用 WriteHeader() 将被忽略并记录警告（如 "multiple WriteHeader calls"），而 Encode() 的写入操作本身不会覆盖已设状态码。
正确做法是：先设置响应头（如 Content-Type），再调用 WriteHeader()，最后编码 JSON 到响应体。示例如下：
func handleError(w http.ResponseWriter, err error, statusCode int) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(statusCode)
// 构建结构化错误响应
errorResponse := map[string]interface{}{
"error": err.Error(),
"code": statusCode,
"timestamp": time.Now().UTC().Format(time.RFC3339),
}
if err := json.NewEncoder(w).Encode(errorResponse); err != nil {
// 注意：此处不能再调用 WriteHeader，因已写入 header
// 建议记录日志，或返回通用服务器错误（但需确保不重复写 header）
log.Printf("Failed to encode JSON error: %v", err)
// 可选：向客户端发送简短文本错误（仅当未开始写入 body 时安全）
http.Error(w, "Internal Server Error", http.StatusInternalServerError)
return
}
}
⚠️ 关键注意事项：
使用约定式提交（Conventional Commits）生成标准化的 Git 提交信息。适用于以下场景： (1) 暂存更改时需要提交信息； (2) 审查 diff 时希望获得结构化摘要； (3) 编写 PR 描述或变更日志（changelog）条目； (4) 用户明确要求“为本次更改编写提交信息”。 该功能会分析已暂存/未暂存的 diff，并生成按类型（type）划分范围的提交信息。
-
顺序不可逆：
WriteHeader()→ 设置 Header →Encode()/Write()； -
中间件/框架干扰：某些路由库（如 Gin、Echo）或自定义中间件可能提前写入响应（例如日志中间件调用
w.Write()），导致状态码被锁定。务必检查调用链中是否存在隐式写入； -
避免多次
WriteHeader：仅调用一次，且必须早于任何Write类操作； -
错误处理要闭环：
json.Encoder.Encode()可能失败（如连接中断），需捕获并妥善处理，防止响应不完整。
总结：Go 的 HTTP 响应机制强调“先定状态，再写内容”。只要严格遵循 Header() → WriteHeader() → Encode() 流程，并排查外部干扰，即可稳定输出带自定义状态码的 JSON 错误响应，兼顾语义清晰性与协议合规性。
