Go HTTP 204响应携带正文时的处理边界

接口删除、更新成功后只想告诉调用方“已经完成”，Go 里常会返回 http.StatusNoContent，也就是 HTTP 204。这里最容易踩的坑是：状态码写成 204 后，又沿用统一响应函数继续写 JSON。204 的协议语义是不带响应内容，Go 的 net/http 会拒绝这次正文写入；客户端也不应该把它当作一段空 JSON 去解码。

204 为什么不能再写正文

RFC 9110 将 204 定义为“成功完成请求且没有额外内容可发送”。它的响应在 header section 结束时就结束，不能包含 content 或 trailers；因此，Content-Type: application/json 并不会让 204 变成合法的 JSON 响应。

Go 标准库把 204 注册为 http.StatusNoContent。ResponseWriter.WriteHeader 负责发送状态，未显式调用时第一次 Write 会隐式发送 200。实际开发中应避免先写 JSON 再试图改成 204，因为响应头一旦写出，状态码已经确定。

服务端用 204 返回成功结果

删除或更新接口如果没有新的资源表示需要返回，可以把元数据放在响应头中，例如更新后的 ETag，然后结束处理函数。注意顺序：设置头、写状态、立刻返回。

func deleteItem(w http.ResponseWriter, r *http.Request) {
	// 业务操作成功后，必要的元数据应在状态头发送前设置。
	w.Header().Set("ETag", `"item-42-v7"`)
	w.WriteHeader(http.StatusNoContent)
	return // 204 没有正文，不要再调用 json.NewEncoder(w).Encode。
}

如果统一封装函数无论状态码都执行 JSON 编码，就会把 204 和 200 混在一起。可以让封装函数显式区分“无正文成功”和“带正文成功”，不要仅凭结果对象是否为空来猜。

客户端先判断状态码，再决定是否解码

客户端拿到 204 时，resp.Body 仍应关闭，但没有必要把它解码成 map 或结构体。相反，200、201 等允许携带 content 的状态，需要按接口约定读取并校验 JSON。

func callDelete(client *http.Client, url string) error {
	// Do 返回成功响应后，Body 无论是否有内容都必须关闭。
	resp, err := client.Delete(url)
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	if resp.StatusCode == http.StatusNoContent {
		// 204 的成功信号就是状态码，不读取、不解码正文。
		return nil
	}
	if resp.StatusCode = 300 {
		return fmt.Errorf("delete failed: %s", resp.Status)
	}
	// 其他 2xx 是否有正文由接口契约决定，这里才进入解码分支。
	return nil
}

如果服务端错误地返回了 204 后仍发送字节，客户端也不能把这些字节当成稳定协议。应先修正服务端状态码：需要返回错误详情时使用 4xx/5xx，需要返回结果对象时使用 200 或 201。

排查“204 还有正文”时看这张清单

另一个细节是 WriteHeader 只能有效设置一次状态。排查时不要只看业务函数里的数字，还要看认证、日志、压缩和统一响应中间件有没有提前写出响应。

相关问题

204 和 200 空响应应该怎么选？

如果接口契约明确表示成功后没有表示内容，选 204；如果客户端需要读取 JSON、提示字段或资源表示，选 200。

204 成功后还能返回 ETag 吗？

可以。ETag 属于响应头元数据，不是响应正文；应在调用 WriteHeader 前设置。

客户端需要调用 io.ReadAll(resp.Body) 吗？

不需要为 204 读取正文，但仍要关闭 Body。对其他可能有正文的响应，再按协议读取到合适的程度并处理错误。