Go 写入响应正文后再设置状态码为什么无效

在 Go 的 HTTP Handler 里，最容易被忽略的顺序是：WriteHeader 和响应正文不是两次互相独立的提交。ResponseWriter.Write 第一次被调用时，如果还没有显式状态码，标准库会先按 200 OK 处理，所以正文已经写出后再调用 WriteHeader(http.StatusBadRequest)，客户端仍可能收到 200。

第一次 Write 为什么会让后面的 WriteHeader 失效

ResponseWriter 可以理解为 Handler 和 HTTP 响应之间的提交边界。Header() 保存待发送的响应头，WriteHeader 提交状态码，而 Write 提交正文；但第一次正文写入也会触发隐式的 WriteHeader(http.StatusOK)。因此下面的错误写法不是“状态码参数错了”，而是提交时机已经晚了：

func badHandler(w http.ResponseWriter, r *http.Request) {
    // 正文第一次写入时，ResponseWriter 会隐式提交 200 OK。
    _, _ = io.WriteString(w, "参数格式不正确")

    // 这一行发生在响应已经提交之后，不能把 200 改成 400。
    w.WriteHeader(http.StatusBadRequest)
}

标准库文档还说明，重复提交最终状态码会被忽略，并可能记录 superfluous response.WriteHeader call。排查时先看第一个写入点，不要只盯着最后一行状态码。

正确顺序是先准备 Header，再提交状态码和正文

一个确定的响应路径最好只保留一个最终状态码。响应头要在第一次 WriteHeader 或 Write 之前设置，状态码紧接着提交，正文放在最后：

func badRequest(w http.ResponseWriter, message string) {
    // Content-Type 必须在响应提交前设置。
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")

    // 先确定错误状态，再写错误正文。
    w.WriteHeader(http.StatusBadRequest)
    _, _ = io.WriteString(w, message)
}

如果是成功响应，也可以省略显式的 WriteHeader(http.StatusOK)，但仍然要把 Header 的设置放在正文之前。遇到需要返回错误码的路径时，显式调用通常更清楚。

错误分支为什么要在写正文后立即返回

很多接口先写了错误提示，却没有 return，随后成功分支又继续写数据。这样既可能出现两个状态码，也可能让正文混在一起。把错误响应封装成“设置状态码、写正文、返回”的小路径，能让 Handler 的提交边界更明显：

func userHandler(w http.ResponseWriter, r *http.Request) {
    id, err := strconv.Atoi(r.URL.Query().Get("id"))
    if err != nil {
        // 错误路径一次性提交响应，提交后不再落入成功分支。
        http.Error(w, "id 必须是整数", http.StatusBadRequest)
        return
    }

    // 业务处理完成后再写成功响应。
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(http.StatusOK)
    _, _ = fmt.Fprintf(w, `{"id":%d}`, id)
}

http.Error 适合简单文本错误；如果项目有统一 JSON 错误格式，就自己按相同顺序设置 Content-Type、调用 WriteHeader、写 JSON，再立即返回。不要在 helper 返回后又写一次“默认成功”正文。

业务结果不确定时先计算，再选择最终响应

如果业务函数可能失败，不要先把“处理中”或半截 JSON 写给客户端，再根据后续错误尝试改状态码。先得到结果，再统一提交，可以把业务判断和 HTTP 提交分成两个阶段：

func reportHandler(w http.ResponseWriter, r *http.Request) {
    // 先准备结果，暂时不要触碰 ResponseWriter。
    payload, err := buildReport(r.Context())
    if err != nil {
        http.Error(w, "报表生成失败", http.StatusInternalServerError)
        return
    }

    // 结果确定后再提交 Header、状态码和正文。
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(http.StatusOK)
    _, _ = w.Write(payload)
}

这里的关键不是强行把所有响应都缓存在内存，而是避免在最终状态还没确定时调用 Write。对于流式下载、Server-Sent Events 等必须边生成边发送的场景，状态码和普通响应头更要在第一块数据前完成；后续只能发送正文或已声明的 Trailer，不能再改普通状态。

常见问题

只调用 WriteHeader 不写正文可以吗？

可以。它会提交状态码，是否有正文由具体状态和 Handler 逻辑决定；如果是错误响应，通常仍应给客户端简短可读的错误信息。

Header 在 Write 之后再设置一定无效吗？

对普通响应头来说通常无效，因为响应头已经提交。Trailer 是特殊机制，需要在提交前声明，并按 Trailer 规则写入。

为什么日志里出现重复 WriteHeader？

常见原因是某个 helper 已经写了错误响应，外层 Handler 没有 return；也可能是中间件和业务 Handler 都试图决定最终状态。沿调用链找到第一次 Write 或 WriteHeader，保留一个最终响应责任方即可。