Go Gock 没有匹配的请求为什么返回错误而不访问网络

Go Gock 没有匹配的请求时返回错误，是它在测试场景下有意保留的网络隔离行为，不是请求自动绕过 mock 直接访问真实服务。Gock 会先拦截由 http.Client 发出的请求，再按已声明的 mock 条件匹配；找不到匹配项时，默认把请求结束为错误。只有显式启用真实网络，未匹配请求才可能继续向外发送。

官方地址：https://github.com/h2non/gock

API 文档：https://pkg.go.dev/gopkg.in/h2non/gock.v1

所以排查顺序应该是：先确认请求是否被 Gock 拦截，再核对方法、主机、路径、查询参数、请求头和请求体，最后才决定测试是否真的需要访问网络。不要一看到错误就把 EnableNetworking 加上，这会把原本应该暴露的 mock 漏配隐藏起来。

先把“没有匹配”与“服务返回错误”分开

这类问题通常出现在测试刚从直接调用服务改成 HTTP mock 的阶段。调用代码仍然执行了 client.Do(req)，但测试里声明的 mock 只覆盖了另一种 method 或路径，于是调用方收到的是传输层错误，而不是目标服务返回的 4xx 或 5xx。

可以按下面的时间线判断故障位置：

1. 测试注册 mock，并开启 Gock 的请求拦截。
2. 业务代码创建请求，可能使用默认 client，也可能使用自定义 client。
3. Gock 读取请求的 method、URL、参数、请求头和 body，与声明池里的 mock 条件比较。
4. 匹配成功时返回 mock 响应；全部不匹配时，默认返回错误，不触发真实网络。

如果日志中没有服务端状态码，或者错误发生在读取响应之前，优先检查 mock 匹配而不是远端服务。Gock 的官方说明把匹配池描述为按声明顺序处理，且未匹配请求在未开启真实网络时会解析为错误。

Gock 先拦截，再决定是否能匹配

Gock 通过 http.RoundTripper 参与 net/http 请求。对默认 transport，通常由 gock.Intercept() 开始拦截；如果业务使用了独立的 http.Client，则需要针对该 client 调用 gock.InterceptClient(client)。

这里最容易误判的一点是：Gock 找不到 mock 并不代表目标地址不存在，也不代表 DNS、TLS 或远端路由失败。请求可能根本没有离开本进程。这个差异正是测试隔离的价值：测试可以明确告诉你“这个调用没有被声明”，而不是悄悄访问外部系统。

按 FIFO 规则核对每一项匹配条件

mock 的声明看起来很接近，仍可能因为一个字段不同而完全不匹配。建议按照固定顺序核对：

下面的示例故意把 mock 声明放在测试逻辑前面，并在测试结束后关闭拦截。代码中的注释说明了每个关键动作；它是写作示例，不表示本文已经执行过该请求。

func TestCreateUser(t *testing.T) {
	// 测试结束时清空 mock，并关闭 Gock 的拦截状态。
	defer gock.Off()

	// 主机、方法和路径必须与业务代码最终发出的请求保持一致。
	gock.New("https://api.example.test").
		Post("/users").
		MatchType("json").
		JSON(map[string]string{"name": "Ada"}).
		Reply(201).
		JSON(map[string]any{"id": "u-100"})

	// 只有在 mock 声明之后才进入调用逻辑，避免请求先于 mock 注册。
	res, err := http.Post("https://api.example.test/users", "application/json", strings.NewReader(`{"name":"Ada"}`))
	if err != nil {
		t.Fatalf("请求未匹配: %v", err)
	}
	defer res.Body.Close() // 读取响应后关闭 body，避免测试资源泄漏。
}

如果实际请求带有动态 query、JSON 字段顺序变化或额外 header，不要只盯着 mock 的主机字符串。先确认 request 的最终形态，再决定哪些条件必须严格匹配，哪些条件适合使用 Gock 提供的参数或自定义 matcher。

默认隔离与真实网络是两条明确策略

对单元测试而言，默认“未匹配即失败”通常比自动访问网络更安全。它能阻止测试依赖外部服务、避免把真实数据写入远端，也能让 mock 声明缺失尽快暴露。

如果测试确实要让某个请求访问真实网络，Gock 文档提供了 gock.EnableNetworking()，也支持把网络能力绑定到具体 mock。真实网络必须与测试目的匹配，并且把关闭动作写进清理逻辑：

func TestWithRealNetwork(t *testing.T) {
	// 无论测试通过还是失败，都恢复默认的网络隔离策略。
	defer gock.Off()
	defer gock.DisableNetworking()

	// 只有明确需要真实服务时才放行未匹配请求。
	gock.EnableNetworking()
	gock.New("https://status.example.test").
		Get("/health").
		Reply(200).
		JSON(map[string]string{"status": "mocked"})

	// /health 仍可使用 mock；其它未匹配请求才可能进入真实网络。
	res, err := http.Get("https://status.example.test/health")
	if err != nil {
		t.Fatalf("请求失败: %v", err)
	}
	defer res.Body.Close() // 关闭响应体，避免网络测试留下连接资源。
}

不要用全局启用真实网络来掩盖一个漏写的 mock。如果测试只是验证请求参数，应该修正 mock；只有测试本身就是集成测试，或者特意验证真实网络行为时，才把放行策略写得足够明显。

自定义 http.Client 要拦截对对象

默认 client 和自定义 client 是另一个高频分界。Gock 官方 API 区分了 Intercept() 与 InterceptClient(client)：后者用于自定义 transport 或自定义 RoundTripper 的 client。业务代码如果没有使用被拦截的那个对象，mock 配得再准确也不会生效。

func TestCustomClient(t *testing.T) {
	client := &http.Client{Timeout: 2 * time.Second}

	// 只拦截本测试实际使用的自定义 client。
	gock.InterceptClient(client)
	defer gock.RestoreClient(client) // 测试结束恢复原 transport。
	defer gock.Off()                 // 清空本次测试的 mock 声明。

	gock.New("https://api.example.test").
		Get("/profile").
		Reply(200).
		JSON(map[string]string{"name": "Ada"})

	req, err := http.NewRequest(http.MethodGet, "https://api.example.test/profile", nil)
	if err != nil {
		t.Fatalf("创建请求失败: %v", err)
	}
	res, err := client.Do(req)
	if err != nil {
		t.Fatalf("自定义 client 未命中 mock: %v", err)
	}
	defer res.Body.Close() // 调用方负责关闭 response body。
}

如果自定义 client 由 SDK 内部创建，测试代码可能拿不到它。此时应从 SDK 的依赖注入入口传入 client，或使用 SDK 官方提供的 transport 配置点，而不是在测试里另建一个看似相同的 client。

用未匹配请求记录补齐排查闭环

Gock 提供 HasUnmatchedRequest 和 GetUnmatchedRequests，可以把已经收到但没有命中 mock 的请求取出来。它们适合帮助定位最终 method 和 URL，尤其是 BaseURL、路径前缀或 query 参数由多层配置拼接时。

func reportUnmatched(t *testing.T) {
	// 只在失败诊断时读取注册表，避免把诊断逻辑混入业务请求。
	if !gock.HasUnmatchedRequest() {
		return
	}

	for _, req := range gock.GetUnmatchedRequests() {
		// Method 和 URL 是最先核对的两个匹配维度。
		t.Logf("未匹配请求: method=%s url=%s", req.Method, req.URL.String())
	}

	// 诊断完成后清理记录，避免下一条测试继承旧信息。
	gock.CleanUnmatchedRequest()
}

这个诊断函数应该在测试失败路径或测试辅助代码中使用。它不能替代对 body 和 header 的检查，但能快速排除“我声明的是这个地址，业务实际发出的却是另一个地址”的错觉。

按故障类型选择修复动作

防止下一次再被同一种错误打断

第一，把 mock 注册集中在测试准备阶段，不要在并发业务逻辑已经启动后才补声明。第二，对自定义 client 建立明确的注入和恢复约定，测试结束时调用 RestoreClient。第三，把 gock.Off() 放进清理路径，避免前一个测试的 mock 影响后一个测试。第四，只有集成测试才允许真实网络，并把 EnableNetworking 作为显眼的测试策略，而不是隐藏在公共初始化函数里。

最后要记住：Gock 的“没有匹配就报错”是在保护测试边界。修复的目标不是让所有请求都能发出去，而是让测试明确知道哪些请求应该被模拟、哪些请求允许触网，以及每种选择在什么时候结束。

为什么 Gock 不匹配时不自动访问真实接口？因为默认网络模式用于隔离测试；未匹配请求直接报错，可以暴露 mock 漏配和请求条件偏差。

打开 EnableNetworking 后还需要写 mock 吗？需要。已声明且匹配的请求仍可返回 mock；只是不匹配的请求获得了访问真实网络的可能，不能把它当作 mock 配置的替代品。

自定义 http.Client 为什么一直命中不了？通常是只调用了默认拦截，却没有对实际使用的自定义 client 调用 InterceptClient，或者 client 的 transport 后来又被替换。