Go httptest.NewRequest 怎么构造带主机和 TLS 状态的测试请求

我在写 Handler 单元测试时，最容易漏掉的不是路径，而是请求的主机名和 TLS 状态：只传入 /invoices，Handler 看到的 Host 默认是 example.com；如果要覆盖 HTTPS 分支，也不能只在测试名称里写“HTTPS”。更稳妥的做法是用绝对 URL 传给 httptest.NewRequest，再按需要检查或覆盖 req.Host。

官方文档：https://pkg.go.dev/net/http/httptest#NewRequest

http:// 目标会生成入站测试请求并带有主机名，https:// 目标会让 req.TLS 变成非 nil 的 dummy 值；这只是在构造 Handler 输入，不会启动测试服务器，也不会完成真实 TLS 握手。

先选对 NewRequest：它构造的是入站请求

httptest.NewRequest 返回的是适合直接交给 http.Handler 的服务端请求。它和 http.NewRequest 的用途不同：后者面向客户端发送，URL 的主机主要用于连接目标；前者模拟已经到达 Handler 的请求，Host、URL.Path、RequestURI 和 TLS 才是测试重点。

用绝对 URL 构造指定 Host 的请求

如果测试要区分租户、虚拟主机或回调域名，直接把主机写进绝对 URL。目标为 http://billing.example.test/invoices?page=2 时，Handler 可以从 r.Host 读取 billing.example.test，从 r.URL.Path 读取 /invoices，查询参数仍在 r.URL.RawQuery 中。

package httphandler_test

import (
	"net/http/httptest"
	"testing"
)

func TestRequestTargetFields(t *testing.T) {
	// 绝对 URL 同时表达协议、主机、路径和查询串。
	req := httptest.NewRequest("GET", "http://billing.example.test/invoices?page=2", nil)

	// 入站请求的 Host 供 Handler 做虚拟主机或租户判断。
	if req.Host != "billing.example.test" {
		t.Fatalf("unexpected host: %q", req.Host)
	}
	// URL.Path 保留路径，RawQuery 保留问号后的查询部分。
	if req.URL.Path != "/invoices" || req.URL.RawQuery != "page=2" {
		t.Fatalf("unexpected target: %s?%s", req.URL.Path, req.URL.RawQuery)
	}
}

只传路径也可以，但这时文档约定 Host 使用 example.com。因此，涉及 Host 的测试不要依赖默认值；把期望的主机写入目标字符串，测试意图会更清楚。

用 https 目标覆盖 TLS 分支

把 scheme 改成 https 后，NewRequest 会给请求设置一个非 nil 的 dummy TLS 状态。它适合测试“仅 HTTPS 才允许访问”或“根据 r.TLS 选择跳转策略”的 Handler 分支。HTTP 与 HTTPS 的字段差异可以概括为：Host 都来自绝对 URL，TLS 只在 HTTPS 目标下非 nil。

func TestHTTPSOnlyHandlerInput(t *testing.T) {
	// https scheme 只用于构造 TLS 元数据，不会发起真实网络握手。
	req := httptest.NewRequest("GET", "https://billing.example.test/invoices", nil)

	// Handler 可以用 TLS 是否为 nil 判断请求是否带 HTTPS 语义。
	if req.TLS == nil {
		t.Fatal("expected a non-nil dummy TLS state")
	}
	if req.Host != "billing.example.test" {
		t.Fatalf("unexpected host: %q", req.Host)
	}
}

这个请求不能证明证书、密码套件、SNI 或 HTTP/2 协商结果。需要覆盖这些网络行为时，应另行使用真实的测试服务端；本文只讨论把正确的元数据交给 Handler。

Host 覆盖、请求体和常见边界

绝对 URL 是构造 Host 的首选，但某些测试要模拟“URL 指向一个地址、Host 头是另一个值”的场景，可以在创建后覆盖 req.Host。请求体则建议传入 bytes.Reader、strings.Reader、bytes.Buffer 或 http.NoBody，标准库会据此设置 ContentLength。

func TestOverrideHostAndBody(t *testing.T) {
	// 这里的 body 类型可让 NewRequest 推导出明确的 ContentLength。
	body := strings.NewReader(`{"status":"paid"}`)
	req := httptest.NewRequest("POST", "https://gateway.example.test/payments", body)

	// 覆盖入站 Host，用于模拟代理转发后的 Host 头。
	req.Host = "tenant.example.test"
	if req.Host != "tenant.example.test" || req.ContentLength 

上面的示例需要补充 strings 导入；正文只强调字段关系，不建议为了测试而手动改写一整套 http.Request。另外，空 method 会按 GET 处理，非法 target 会直接 panic，所以 target 应使用固定、可读的测试数据。

相关问题

httptest.NewRequest 会启动端口监听吗？不会。它只在内存中构造一个适合 Handler 的入站请求；需要网络连接、证书或客户端行为时，再使用 httptest.Server 体系。

为什么路径写法得到的 Host 是 example.com？这是标准库为相对 target 设定的默认 Host。测试业务 Host 时直接传绝对 URL，或在创建后明确覆盖 req.Host。

HTTPS 的 req.TLS 非 nil 是否代表真实证书有效？不代表。它只是让 Handler 能判断 HTTPS 语义的 dummy 状态，不包含真实握手、证书校验或协商结果。