HTTP 传输头

在 Go 的 net/http 中，Transfer-Encoding 不是普通的“写进请求头就算完成”的字段。不要把它当成普通 Header 用 Header.Set 强行覆盖：请求真正写出时，Go 会根据 Body、ContentLength、Request.TransferEncoding 以及协议版本重新组织传输字段。

如果请求体长度已知，优先让 http.NewRequest 和 Transport 使用 Content-Length；如果长度未知，让 HTTP/1.1 的 Transport 自动选择分块传输；只有确实需要表达传输语义时，才设置 Request.TransferEncoding。HTTP/2 则应按帧传输理解，不能继续拿 HTTP/1.1 的 chunked 头去判断。

官方资料：https://pkg.go.dev/net/http

Header 与 Request 字段不是同一层

很多问题都从下面这段代码开始：它看起来像是在设置请求头，但它没有真正表达 Go 传输层需要的控制字段。

package main

import "net/http"

func wrongEntry(url string) (*http.Request, error) {
	// 这里的 Header 只是在普通头部映射中放入一个字符串。
	req, err := http.NewRequest(http.MethodPost, url, nil)
	if err != nil {
		return nil, err
	}
	// Transfer-Encoding 属于 net/http 的传输语义，不应只靠 Header.Set 表达。
	req.Header.Set("Transfer-Encoding", "chunked")
	return req, nil
}

Request.Write 的文档明确把 Host、Content-Length、Transfer-Encoding 和 Trailer 列为由 Request 其他字段推导的特殊字段。因此，查看 req.Header.Get("Transfer-Encoding") 只能说明映射里有这个值，不能说明它最终会按这个值写到线路上。

先让请求体和长度表达真实情况

最稳妥的做法不是先想“怎么加 Transfer-Encoding”，而是先回答两个问题：请求有没有 Body，以及 Body 的长度是否已经知道。已知长度时，标准库可以写出 Content-Length；长度未知但仍然是 HTTP/1.1 请求时，Transport 才有条件选择 chunked。

package main

import (
	"bytes"
	"fmt"
	"net/http"
)

func knownLengthRequest(url string) (*http.Request, error) {
	payload := []byte(`{"name":"go"}`)
	// bytes.Reader 的长度可以被 NewRequest 识别，适合固定大小的请求体。
	req, err := http.NewRequest(http.MethodPost, url, bytes.NewReader(payload))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Content-Type", "application/json")
	fmt.Println("ContentLength:", req.ContentLength)
	return req, nil
}

对于流式生成、管道读取等场景，长度可能在发送前无法确定。这时不要伪造一个 Content-Length，也不要把同一个语义同时塞进普通 Header。让请求保持未知长度，Transport 才能根据 HTTP/1.1 的规则选择分块传输。

package main

import (
	"io"
	"net/http"
)

func unknownLengthRequest(url string, body io.Reader) (*http.Request, error) {
	// 自定义 Reader 的长度通常无法提前得到，NewRequest 会保留未知长度语义。
	req, err := http.NewRequest(http.MethodPost, url, body)
	if err != nil {
		return nil, err
	}
	// 不猜测长度，也不在 Header 中伪造 Transfer-Encoding。
	req.ContentLength = -1
	return req, nil
}

这里的“自动”不是忽略了请求体，而是由标准库统一处理消息体、长度、分块以及连接复用之间的关系。图2把常见输入条件和应观察的传输结果放在一起。

确实需要时设置 Request.TransferEncoding

如果你正在实现需要明确 HTTP/1.1 分块语义的客户端适配层，可以直接设置 Request 的字段，而不是设置同名 Header：

package main

import (
	"bytes"
	"net/http"
)

func explicitChunkedRequest(url string, payload []byte) (*http.Request, error) {
	req, err := http.NewRequest(http.MethodPost, url, bytes.NewReader(payload))
	if err != nil {
		return nil, err
	}
	// 显式告诉 net/http 使用 HTTP/1.1 的 chunked 传输语义。
	req.TransferEncoding = []string{"chunked"}
	// chunked 与 Content-Length 不能同时表达同一个请求体长度。
	req.ContentLength = -1
	return req, nil
}

这段写法只是在 Request 层表达意图，最终是否以 HTTP/1.1 发送仍取决于客户端 Transport 和协商出的协议。对于一般业务请求，它通常没有必要，因为库已经能根据已知或未知长度自动选择。

如果要明确表示不使用分块传输，可以使用 identity 语义，但前提是你知道下游和协议边界：

package main

import "net/http"

func identityRequest(url string, body *http.Request) *http.Request {
	// identity 表示不使用 chunked；调用方仍需保证消息体边界可以被正确判断。
	body.TransferEncoding = []string{"identity"}
	return body
}

实际项目里更常见的选择是：固定内容用可识别长度的 Reader，流式内容保持未知长度，只有协议适配或测试场景才直接修改 TransferEncoding。

按协议版本排查“头部不见了”

如果日志里看到了 Transfer-Encoding: chunked，但对端或抓包工具没有显示它，先确认协议版本和观察位置：

• HTTP/1.1：未知长度的请求体可以使用 chunked，消息头和分块边界属于 HTTP/1.1 的线格式。
• HTTP/2：请求使用二进制帧传输，不应把 HTTP/1.1 的 chunked 头当成判断 HTTP/2 请求体边界的依据。
• 请求写出前：Header.Get 看到的只是内存中的 Header 映射；真正的线格式要看 Request 的传输字段和 Transport 的写出路径。
• 代理链路中：代理可能终止一段连接并重新编码另一段，前后两段出现不同表现不一定是 Go 请求对象失效。

排查时可以先打印请求的协议、长度和传输字段，但不要把打印值当成线上抓包结果：

package main

import (
	"fmt"
	"net/http"
)

func describe(req *http.Request) {
	// 这些字段用于定位发送前的状态，不代表代理之后的最终线格式。
	fmt.Printf("proto=%s contentLength=%d transferEncoding=%v body=%t\n",
		req.Proto, req.ContentLength, req.TransferEncoding, req.Body != nil)
}

一张表记住正确入口

结语：先表达长度，再决定传输

“HTTP 传输头”这个问题的关键不在于记住一个特殊拼写，而在于区分普通 Header 和 net/http 的传输控制字段。Header.Set 可以设置很多业务头，但 Transfer-Encoding、Content-Length 等字段需要由 Request 的结构化状态统一推导。固定长度就交给库生成长度；未知长度就保持真实并让 HTTP/1.1 Transport 选择分块；只有适配协议时才直接设置 Request.TransferEncoding。

常见问题

为什么 Header.Get 能读到 Transfer-Encoding，但对端没有收到？

因为 Header 映射里的值不等于 Request 写出时采用的传输字段。Go 会从 Body、ContentLength 和 TransferEncoding 重新组织特殊字段。

设置了 ContentLength=-1 就一定会出现 chunked 吗？

不一定。它表达的是长度未知；是否使用 chunked 还要看请求有无 Body、客户端采用的协议以及 Transport 的发送策略。HTTP/2 也不按 HTTP/1.1 chunked 头解释。

普通 JSON POST 需要手动设置 Transfer-Encoding 吗？

通常不需要。用 bytes.Reader、strings.Reader 等能提供长度的 Reader 创建请求，让标准库自动写出合适的长度字段即可。