3、HTTP契约测试：net/http/httptest包、模拟HTTP服务器、请求/响应匹配、状态码验证

3.2 模拟HTTP服务器的构建模式

构建模拟服务器时，最常用的模式是传入一个自定义的 http.Handler，该Handler根据请求路径、方法或Header返回预设的响应。以下是一个典型的服务器构建流程：

// 创建模拟服务器，返回固定JSON响应
mockServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    // 1. 请求匹配：验证路径和方法
    if r.Method != http.MethodGet || r.URL.Path != "/api/v1/users" {
        w.WriteHeader(http.StatusNotFound)
        return
    }
    // 2. 设置响应Header
    w.Header().Set("Content-Type", "application/json")
    // 3. 写入状态码和Body
    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"users":[{"id":1,"name":"Alice"}]}`))
}))
defer mockServer.Close()

// 客户端使用mockServer.URL发起请求
resp, err := http.Get(mockServer.URL + "/api/v1/users")

3.3 请求/响应匹配策略

契约测试的核心在于“匹配”。Go标准库提供了丰富的匹配手段，从简单的路径匹配到复杂的Header和Body校验。下表总结了常用的匹配维度及对应方法：

3.4 状态码验证的完整闭环

状态码验证是契约测试中最直观的断言点。一个完整的验证闭环包括：模拟服务器返回特定状态码 → 客户端接收并断言 → 根据断言结果决定测试通过/失败。以下是一个包含正向和负向测试的完整示例：

func TestUserAPI_StatusCode(t *testing.T) {
    // 创建模拟服务器
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        switch {
        case r.Method == http.MethodGet && r.URL.Path == "/api/v1/user/1":
            w.WriteHeader(http.StatusOK)
            w.Write([]byte(`{"id":1,"name":"Bob"}`))
        case r.Method == http.MethodGet && r.URL.Path == "/api/v1/user/999":
            w.WriteHeader(http.StatusNotFound)
            w.Write([]byte(`{"error":"user not found"}`))
        default:
            w.WriteHeader(http.StatusMethodNotAllowed)
        }
    }))
    defer server.Close()

    // 正向测试：期望200
    resp, _ := http.Get(server.URL + "/api/v1/user/1")
    if resp.StatusCode != http.StatusOK {
        t.Errorf("expected 200, got %d", resp.StatusCode)
    }

    // 负向测试：期望404
    resp, _ = http.Get(server.URL + "/api/v1/user/999")
    if resp.StatusCode != http.StatusNotFound {
        t.Errorf("expected 404, got %d", resp.StatusCode)
    }

    // 方法不允许测试：期望405
    resp, _ = http.Post(server.URL+"/api/v1/user/1", "application/json", nil)
    if resp.StatusCode != http.StatusMethodNotAllowed {
        t.Errorf("expected 405, got %d", resp.StatusCode)
    }
}

3.5 契约测试流程总览

下图展示了使用 httptest 进行HTTP契约测试的完整数据流与决策路径：

3.6 高级匹配：使用第三方断言库

当响应Body结构复杂时，仅靠字符串比较容易产生误判。推荐结合 github.com/stretchr/testify/assert 或 github.com/google/go-cmp/cmp 进行结构化匹配：

import (
    "net/http/httptest"
    "testing"
    "github.com/stretchr/testify/assert"
)

func TestJSONResponseMatch(t *testing.T) {
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusOK)
        w.Write([]byte(`{"status":"ok","data":{"count":42}}`))
    }))
    defer server.Close()

    resp, _ := http.Get(server.URL + "/check")
    defer resp.Body.Close()

    // 使用testify进行JSON相等断言
    expected := `{"status":"ok","data":{"count":42}}`
    assert.Equal(t, http.StatusOK, resp.StatusCode)
    assert.JSONEq(t, expected, readBody(resp.Body))
}

func readBody(body io.ReadCloser) string {
    b, _ := io.ReadAll(body)
    return string(b)
}

3.7 常见故障模式与排查

在实际的契约压测闭环中，以下故障模式频繁出现，需要重点排查：

• 状态码不匹配： 模拟Handler中未正确设置 w.WriteHeader()，或设置顺序晚于 w.Write()（Go默认写入200）。
• Body解析失败： 未设置 Content-Type Header，导致客户端解析JSON时报错。
• 路径匹配遗漏： 模拟Handler中使用了硬编码路径，但客户端请求携带了尾部斜杠或查询参数。
• Header未传递： 客户端设置了自定义Header，但模拟Handler未读取或验证。
• goroutine泄漏： 测试函数提前退出，未调用 server.Close()。

3.8 契约测试的边界条件

在编写HTTP契约测试时，除了常规的正向路径，必须覆盖以下边界条件：

通过系统性地覆盖这些边界条件，可以显著提升契约测试的鲁棒性，避免在压测阶段暴露意外故障。