Go Gock 怎样为自定义 http.Client 安装拦截器

自定义 http.Client 使用 Gock 时，在请求发出前调用 gock.InterceptClient(client)，并确保被测逻辑使用的就是这个 client。测试结束后调用 gock.RestoreClient(client) 恢复它原来的 Transport，再清理 Gock 的全局模拟状态。只声明模拟规则，并不能保证任意自定义传输器都已经被包进拦截器。

Gock 官方项目：https://github.com/h2non/gock

现象：规则已经写了，请求却没有命中

常见场景是生产代码通过依赖注入取得一个带自定义 Transport 的 client，测试却只给默认客户端声明模拟，或者拦截的是另一个临时创建的 client。此时继续修改 JSON 响应体并不能解决问题，因为请求还没有到达预期的拦截对象。

排查时先区分两种现象：请求根本没有经过 Gock，还是已经经过 Gock但规则不匹配。前者检查实例和 Transport，后者再比较方法、主机、路径、查询参数与请求体。不要一开始就开启真实网络回退来消除报错，否则可能把模拟失败隐藏起来。

分层检查：实例、传输器和规则各管什么

结构中，被测服务和自定义 Client 属于业务调用组；Gock Transport 与原 Transport 属于传输对象组；匹配规则和模拟响应属于模拟定义组。InterceptClient 会把 Gock Transport 安装到 client 上，并保存先前的 Transport。匹配规则仍来自 Gock 管理的模拟集合，不是自动变成 client 私有数据。

修复动作：给实际使用的 client 安装拦截器

下面是可独立保存为 custom_client_test.go 的完整示例。原始 Transport 是一个拒绝回退的测试替身，即使接线错误也不会真的访问外部服务。示例域名用于匹配说明，不是实际 API 地址。

package clientmock

import (
    "encoding/json"
    "errors"
    "net/http"
    "testing"
    "time"

    "github.com/h2non/gock"
)

// 原始传输器只记录意外回退，不访问网络。
type denyTransport struct {
    calls int
}

func (d *denyTransport) RoundTrip(*http.Request) (*http.Response, error) {
    d.calls++
    return nil, errors.New("不允许回退到真实传输")
}

func TestCustomClientInterception(t *testing.T) {
    // Gock 有全局状态，本例不调用 t.Parallel，也不与其他 Gock 测试并发配置。
    gock.OffAll()
    gock.DisableNetworking()
    gock.DisableNetworkingFilters()

    original := &denyTransport{}
    client := &http.Client{
        Transport: original,
        Timeout:   2 * time.Second,
    }
    t.Cleanup(func() {
        // 恢复自定义 client 与清理全局模拟是两个不同动作。
        gock.RestoreClient(client)
        gock.DisableNetworking()
        gock.DisableNetworkingFilters()
        gock.OffAll()
        if client.Transport != original {
            t.Error("原始 Transport 未恢复")
        }
    })

    // 必须拦截被测逻辑实际使用的同一个实例，且在请求发出之前完成。
    gock.InterceptClient(client)
    gock.New("https://api.example.test").
        Get("/v2/ping").
        MatchParam("mode", "demo").
        Reply(http.StatusOK).
        JSON(map[string]string{"status": "ready"})

    // 请求同样使用 client，不使用 http.Get 或另建的 client。
    res, err := client.Get("https://api.example.test/v2/ping?mode=demo")
    if err != nil {
        t.Fatal(err)
    }
    defer res.Body.Close() // 即使响应来自模拟器，也按 HTTP 使用约定关闭响应体。
    if res.StatusCode != http.StatusOK {
        t.Fatalf("状态码不符: %d", res.StatusCode)
    }
    var body struct {
        Status string `json:"status"`
    }
    if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
        t.Fatal(err)
    }
    if body.Status != "ready" {
        t.Fatalf("响应字段不符: %q", body.Status)
    }
    if !gock.IsDone() {
        t.Error("仍有未消费的模拟规则")
    }
    if original.calls != 0 {
        t.Errorf("意外调用原始 Transport: %d", original.calls)
    }
}

模块准备与运行命令如下。本文没有执行该测试，也不把结构配图作为成功运行证据。

# 在独立示例目录初始化模块，已有模块无需重复初始化。
go mod init example.com/clientmock
go get github.com/h2non/gock

# 将代码保存为 custom_client_test.go 后自行执行；本文未运行该命令。
go test -run '^TestCustomClientInterception$' -count=1

代码把清理注册在请求之前，因此后续使用 t.Fatal 提前退出时仍会执行。安装拦截后不要再给 client.Transport 赋一个新值，否则会绕开刚安装的包装。实际业务中，初始化依赖时就把 client 交给服务，测试也使用同一条依赖注入路径。

证据判断：读响应之外，还要知道有没有意外回退

如果只判断响应没有报错，并不能证明它来自目标模拟规则。示例分别判断状态码、业务字段、规则是否消费，以及原 Transport 是否被调用。它们对应不同问题：响应内容是否符合约定、预期请求是否发生、有没有绕过模拟层。

Gock 默认未匹配请求会返回匹配错误；若打开真实网络模式或使用了特定网络规则，行为会改变。为了让这个例子集中体现客户端接线，代码在开始时关闭真实网络并清除网络过滤配置，同时用拒绝回退的原 Transport 再限制一层。

IsDone 说明没有剩余待消费规则，不单独证明所有请求都符合业务预期。对于更复杂的测试，还应按场景理解调用次数、未匹配请求记录和重试行为，而不是将一个布尔值当作完整正确性证明。

恢复清理：自定义对象和全局状态分开处理

RestoreClient 面向指定 client，把原来的 Transport 放回去；Off 或 OffAll 面向 Gock 的默认拦截与模拟状态。OffAll 还会清除未匹配请求记录。仅调用 OffAll，不能把“自定义 client 的 Transport 字段已恢复”当作当然成立的结论。

清理结构可以拆成客户端恢复组和全局清理组：自定义 Client、RestoreClient、原 Transport 属于前者；OffAll、模拟规则池、未匹配记录属于后者。恢复对象引用与清空规则池是两种独立职责，测试中应显式覆盖。

Gock 文档明确提醒其并非所有部分都完全线程安全。不要在请求已经并发执行时继续安装、恢复拦截器或修改规则；应先完成规则和客户端配置，再开始请求，并在请求全部结束后清理。自定义 client 不意味着独享全局模拟池，本例因此没有使用 t.Parallel。

反向判断与收尾清单

若把示例路径改为 /v2/other 而不改规则，预期应是匹配失败，不应悄悄返回原模拟响应；若去掉 InterceptClient，自定义拒绝传输器将成为重要的错误暴露点。这些是读者自行检查接线时可采用的反例，本文未执行它们。

收尾时只需按三个问题核对设计：被测服务拿到的是哪个 client；该 client 的 Transport 是否仍是预期包装；每次测试结束是否同时处理对象恢复与全局状态清理。把这三处边界理清，再检查复杂匹配条件会更直接。

同一个 client 需要每次请求都拦截一次吗？

不需要。通常在场景初始化时安装一次，在请求结束后的清理阶段恢复。反复修改运行中的 client 配置反而会让并发边界不清楚。

恢复 client 后还可以继续用 Gock 模拟它吗？

恢复后它重新使用原 Transport；如果后续场景需要再次模拟，先完成该场景的规则配置并重新安装拦截，不能假定前一次包装仍在。

自定义 Transport 里的鉴权或重试逻辑会被匹配成功的模拟执行吗？

不能据此保证。Gock 包装位于 client 的传输入口，匹配后可直接构造响应；若要测试原传输器内部逻辑，应根据它的依赖结构选择更内层的替身或独立测试，而不是把外层响应模拟当作完整链路覆盖。

参考：Gock 使用与清理说明、InterceptClient 与 RestoreClient API、客户端包装实现。