Go net/http 如何读取 Trailer 头而不是普通 Header

在 Go 的 net/http 客户端里，响应末尾的 Trailer 不能像普通响应头那样直接从 resp.Header 读取。正确顺序是：先检查响应错误，读取 resp.Body 直到返回 io.EOF，再访问 resp.Trailer；最后关闭 Body。Trailer 是跟在响应体之后传输的键值对，Go 会把它和普通 Header 分开保存。

读取 HTTP Trailer 的关键只有一个：不要在 Body 还没读完时读取 Trailer。客户端要读到 EOF 后再查 resp.Trailer.Get("字段名")；服务端要在第一次 WriteHeader 或 Write 之前声明 Trailer。

先分清 Header、Trailer 与声明字段

普通 Header 在响应体之前到达，例如 Content-Type 和 Content-Length。Trailer 则在响应体之后到达，适合只有处理完内容才能计算出的摘要、校验结果或处理状态。它不是把同一个字段“延迟写入” Header，而是另一组可在响应末尾出现的字段。

Go 的 http.Response 会把服务端声明的 Trailer 名称先放进 Trailer 映射，值在 Body 尚未读完时还不可用；这些值不会被补到 Header。因此下面两种读取并不等价：

在 Body 读到 EOF 后读取 Response.Trailer

客户端代码可以把读 Body 和读 Trailer 放在同一个函数里，避免调用方忘记时机。示例使用 io.ReadAll，它只有在读完或遇到错误后才返回；只有错误为 nil 时，才继续使用最终 Trailer。

func readResponse(resp *http.Response) ([]byte, string, error) {
	// 无论读取成功或失败，都要释放响应体
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, "", fmt.Errorf("读取响应体失败: %w", err)
	}

	// 读到 EOF 后，Transport 才能填充服务端发来的 Trailer 值
	checksum := resp.Trailer.Get("X-Checksum")
	return body, checksum, nil
}

如果你手动循环调用 Read，判断条件要以返回的 io.EOF 为准，并且不要在另一个 goroutine 中同时读取 Trailer。官方文档明确要求 Trailer 不能和 Body 的 Read 并发访问。只调用 resp.Body.Close() 而没有把内容读到 EOF 时，不应把 Trailer 当成已经完整到达。

服务端先声明再写入 Trailer

服务端知道 Trailer 名称时，要在第一次 WriteHeader 或 Write 之前声明。之后可以在处理过程中给同名 Header 赋值，Go 会把这些值放到响应末尾，而不是再次写成普通头。

func trailerHandler(w http.ResponseWriter, r *http.Request) {
	// 先声明末尾字段，名称必须早于第一次写响应
	w.Header().Set("Trailer", "X-Checksum")
	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	w.WriteHeader(http.StatusOK)

	// 先写正文，再写只有处理完成后才能确定的值
	_, _ = io.WriteString(w, "payload\n")
	w.Header().Set("X-Checksum", "sha256-placeholder")
}

如果 Trailer 名称直到响应开始后才确定，可以使用 http.TrailerPrefix 机制，但固定字段优先采用显式 Trailer 声明。客户端和中间代理未必都支持 Trailer；跨服务链路上如果需要可靠传递，先确认网关、负载均衡和协议版本不会把末尾字段丢掉。

用检查表排查 Trailer 为空

遇到 resp.Trailer.Get 返回空字符串时，先按数据到达顺序排查，不要马上修改字段大小写或清空连接池。

还要注意 Trailer 不是通用的“响应完成回调”。它只表达协议中随响应传输的末尾头字段，不能替代业务层的 JSON 状态、签名协议或消息队列确认。对于必须跨多个代理可靠传递的结果，通常应把信息放入正文或独立接口，并把 Trailer 作为可选优化。

常见问题

为什么 resp.Header.Get("Trailer") 读不到最终值？

Trailer 只是声明哪些字段会在末尾出现，不是最终字段值本身。最终值应在 Body 读到 EOF 后从 resp.Trailer 读取。

调用 io.ReadAll 后还需要关闭 Body 吗？

需要。读取完成后仍应调用 resp.Body.Close()，让 Transport 释放响应资源并保持连接复用的正常语义。

HTTP/2 下还能使用 Trailer 吗？

可以，但底层传输形式由协议处理，应用仍按 resp.Trailer 和 Body 读完后的时机读取。真正需要确认的是中间代理是否完整转发。