Go httptest.NewServer 实战：从零做一个接口烟雾测试器，检查 JSON、状态码和超时

接口烟雾测试最容易踩的坑就是只盯着200状态码：服务可能返回了错误的 Content-Type，JSON 少了关键字段，或者依赖变慢时一直卡着拖到整个CI任务超时。用 Go 标准库的 httptest.NewServer 可以在本地启动一个真实 HTTP 监听器，再用普通 http.Client 走完整请求链路，几十行代码就能搭出一个够用的接口验收器。

先把检查收敛到四件事：状态码正确、响应类型正确、JSON 关键字段存在、超时能按预期结束。这样一条冒烟测试才有明确的失败边界。

先把接口验收目标缩小到一个可运行的小项目

我们做一个订单摘要接口：收到 GET /api/orders/summary 后返回订单数量和金额。烟雾测试器不负责覆盖所有业务规则，它只回答“服务是否还具备最基本的可调用形态”，非常适合放在提交后的快速检查环节里。

验收条件先写清楚：

• 路径正确时返回 200。
• 响应头包含 application/json。
• JSON 中有 count 和 amount 两个字段。
• 未知路径返回 404，服务故意变慢时客户端在 200 毫秒内结束。

用 httptest.NewServer 启动临时服务

httptest.NewServer 会自动分配临时可用的访问地址，测试结束时调用 Close 回收监听器就好。请求代码使用真实的 http.Client，比直接调用处理函数更接近部署后的调用路径。

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/http/httptest"
    "strings"
    "time"
)

type orderSummary struct {
    Count  int     `json:"count"`
    Amount float64 `json:"amount"`
}

func handler(w http.ResponseWriter, r *http.Request) {
    switch r.URL.Path {
    case "/api/orders/summary":
        w.Header().Set("Content-Type", "application/json; charset=utf-8")
        _ = json.NewEncoder(w).Encode(orderSummary{Count: 3, Amount: 128.5})
    case "/slow":
        time.Sleep(500 * time.Millisecond)
        w.WriteHeader(http.StatusNoContent)
    default:
        http.NotFound(w, r)
    }
}

func main() {
    server := httptest.NewServer(http.HandlerFunc(handler))
    defer server.Close()

    client := &http.Client{Timeout: 200 * time.Millisecond}
    if err := checkSummary(context.Background(), client, server.URL); err != nil {
        panic(err)
    }
    fmt.Println("smoke check passed")
}

func checkSummary(ctx context.Context, client *http.Client, baseURL string) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, baseURL+"/api/orders/summary", nil)
    if err != nil {
        return err
    }
    resp, err := client.Do(req)
    if err != nil {
        return fmt.Errorf("request summary: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return fmt.Errorf("want status 200, got %d", resp.StatusCode)
    }
    if !strings.HasPrefix(resp.Header.Get("Content-Type"), "application/json") {
        return fmt.Errorf("unexpected content type: %q", resp.Header.Get("Content-Type"))
    }

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return fmt.Errorf("read response: %w", err)
    }
    var got orderSummary
    if err := json.Unmarshal(body, &got); err != nil {
        return fmt.Errorf("decode summary: %w", err)
    }
    if got.Count 

这里有两个值得保留的细节。第一，客户端设置了明确的 Timeout，测试不会因为服务端忘记结束而无限等待。第二，checkSummary 同时接收 context.Context 和 *http.Client，以后可以在 CI 中替换成更短的超时或传入取消信号。

状态码、响应头和 JSON 要分三层验收

只比较响应正文很容易把问题藏起来。例如服务把 JSON 改成纯文本，正文看起来仍然像一段 JSON，但浏览器和 SDK 可能已经无法按约定处理。把判断拆成三层，失败信息也更容易定位。

接口返回 404 时也要单独测一下。它能证明测试请求确实经过了路由，而不是因为地址拼错却碰巧拿到了一个默认页面。

func checkNotFound(ctx context.Context, client *http.Client, baseURL string) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, baseURL+"/missing", nil)
    if err != nil {
        return err
    }
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    if resp.StatusCode != http.StatusNotFound {
        return fmt.Errorf("want 404 for missing route, got %d", resp.StatusCode)
    }
    return nil
}

把超时变成可以复查的结果

超时检查不应该只返回“请求失败”。我们需要确认它确实因为客户端期限结束，而不是 DNS、连接地址或服务端主动关闭造成的。调用 errors.Is(err, context.DeadlineExceeded) 可以先判断这一层；不同 Go 版本和 HTTP 路径下错误包装文本可能不同，所以不要把完整错误字符串写死。

func checkTimeout(ctx context.Context, client *http.Client, baseURL string) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, baseURL+"/slow", nil)
    if err != nil {
        return err
    }
    _, err = client.Do(req)
    if err == nil {
        return fmt.Errorf("slow endpoint unexpectedly returned")
    }
    if !strings.Contains(strings.ToLower(err.Error()), "timeout") &&
        !strings.Contains(strings.ToLower(err.Error()), "deadline") {
        return fmt.Errorf("unexpected timeout error: %w", err)
    }
    return nil
}

生产测试里更推荐同时控制客户端和请求上下文的期限。客户端超时覆盖整个 HTTP 交换过程，context 则能让调用方在更上层统一取消。两者都设置时，取先到的那个边界；不要把时间写成几秒甚至几十秒，否则冒烟测试会失去“快速反馈”的意义。

接入 go test 前，先让失败信息能指导修复

把示例中的 main 改成测试函数即可接入项目。每个检查都返回带上下文的错误，CI 日志里能直接看到是状态、类型、JSON 还是超时出问题。

func TestOrderSummarySmoke(t *testing.T) {
    server := httptest.NewServer(http.HandlerFunc(handler))
    defer server.Close()

    client := &http.Client{Timeout: 200 * time.Millisecond}
    ctx := context.Background()
    checks := []struct {
        name string
        run  func(context.Context, *http.Client, string) error
    }{
        {"summary", checkSummary},
        {"missing route", checkNotFound},
        {"timeout", checkTimeout},
    }
    for _, check := range checks {
        t.Run(check.name, func(t *testing.T) {
            if err := check.run(ctx, client, server.URL); err != nil {
                t.Fatal(err)
            }
        })
    }
}

在本地运行 go test -run TestOrderSummarySmoke -v，应该看到三个子测试都通过。为了避免测试本身变成慢任务，还可以把 /slow 的等待时间改成 500 毫秒、客户端期限保持 200 毫秒，并在代码评审时明确这组数字是测试边界，不是业务 SLA。

常见问题：这类烟雾测试什么时候值得保留

httptest.NewServer 和直接调用 Handler 有什么区别？

直接调用 Handler 更适合验证纯业务分支；NewServer 会经过 URL、HTTP 方法、响应头和客户端超时，更适合做接口形态的快速验收。

为什么不只检查状态码？

状态码只能说明请求被处理了，不能证明响应能被客户端按约定解析。Content-Type 和关键 JSON 字段缺一不可。

超时测试会不会在低配置机器上不稳定？

如果等待时间和客户端期限相差太小，确实可能抖动。让服务等待时间至少是期限的两倍，并只断言“在期限内失败且属于超时类错误”，不要断言精确毫秒数。

最后保留一份小而明确的验收清单

• 服务启动后，测试请求使用 server.URL，不写固定端口。
• 每个响应都关闭 Body，避免测试批量运行时积累连接资源。
• 成功路径检查状态码、Content-Type 和关键 JSON 字段。
• 异常路径至少覆盖 404 和超时，并输出可定位的错误上下文。
• 通过 go test -run 单独运行这组检查，再决定是否接入整个 CI 阶段。