Golang如何测试REST接口详解

本文深入解析了Go语言中测试REST接口的两大核心方法——使用`httptest.NewServer`进行贴近生产环境的集成测试，以及利用`httptest.NewRecorder`实现快速精准的单元测试，清晰对比了二者适用场景（如验证完整HTTP流程vs.聚焦handler逻辑）、关键陷阱（如端口泄漏、硬编码URL、中间件与路由缺失）及实战技巧（动态URL拼接、Context注入、Body重置、超时/重定向/错误边界控制），并提供了可直接复用的测试范例，帮助开发者构建健壮、可靠且覆盖全面的API测试体系。

用 httptest.NewServer 启动真实 HTTP 服务做集成测试

当你要验证接口行为是否符合外部调用预期（比如 JSON 结构、状态码、Header），而不是只测 handler 内部逻辑时，httptest.NewServer 更贴近真实场景。它会启动一个监听本地端口的临时 HTTP 服务，返回可直接请求的 *httptest.Server 实例。

常见错误是误用 httptest.NewRecorder 去模拟整个服务调用链——它不走网络层，无法测试中间件、路由匹配失败、重定向、TLS 配置等。

• 必须手动调用 server.Close()，否则端口不释放，连续测试会报 address already in use
• URL 是动态生成的（如 http://127.0.0.1:34212），不能硬编码；应通过 server.URL 拼接路径
• 默认不启用 HTTPS，若测试中依赖 req.TLS 或强制跳转，需额外配置 httptest.NewUnstartedServer + 手动启动 TLS listener

func TestAPIWithRealServer(t *testing.T) {
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if r.Method != "GET" || r.URL.Path != "/users" {
            http.Error(w, "not found", http.StatusNotFound)
            return
        }
        json.NewEncoder(w).Encode([]map[string]string{{"name": "alice"}})
    }))
    defer server.Close() // 必须 defer
<pre class="brush:php;toolbar:false;">resp, err := http.Get(server.URL + "/users")
if err != nil {
    t.Fatal(err)
}
defer resp.Body.Close()

if resp.StatusCode != http.StatusOK {
    t.Errorf("expected 200, got %d", resp.StatusCode)
}

}

用 httptest.NewRecorder 测试单个 handler 的响应细节

这是最轻量、最快的方式，适合单元测试：绕过网络栈，把请求直接“注入”到 handler，捕获其对 http.ResponseWriter 的所有写入（状态码、Header、Body）。

注意它不会执行路由匹配，也不会触发 http.ServeMux 的路径前缀处理，所以传入的 *http.Request 必须手动构造好 URL.Path 和 Method。

• req := httptest.NewRequest("POST", "/login", strings.NewReader(`{"user":"a"}`)) 中，路径和方法必须与 handler 实际期望的一致
• 若 handler 依赖 context.WithValue 注入的数据（如用户 ID、trace ID），需在 request 上显式设置：req = req.WithContext(context.WithValue(req.Context(), key, value))
• Body 是 io.ReadCloser，若多次读取（如解析两次 JSON），需用 req.Body = ioutil.NopCloser(bytes.NewReader(buf)) 重置

func TestLoginHandler(t *testing.T) {
    req := httptest.NewRequest("POST", "/login", strings.NewReader(`{"username":"test","password":"123"}`))
    req.Header.Set("Content-Type", "application/json")
<pre class="brush:php;toolbar:false;">rr := httptest.NewRecorder()
handler := http.HandlerFunc(loginHandler)
handler.ServeHTTP(rr, req)

if status := rr.Code; status != http.StatusOK {
    t.Errorf("handler returned wrong status code: got %v want %v",
        status, http.StatusOK)
}

var res map[string]string
if err := json.Unmarshal(rr.Body.Bytes(), &res); err != nil {
    t.Fatal(err)
}
if res["token"] == "" {
    t.Error("expected non-empty token")
}

}

测试带中间件的 handler 链（如 JWT 校验、日志）

中间件本质是包装 handler 的函数，测试时只需把最终组合后的 handler 传给 httptest.NewRecorder，不需要 mock 中间件本身。

容易忽略的是中间件可能修改 request context 或写入 Header，这些都会反映在 Recorder 中，但不会自动触发 panic 捕获或 panic recovery 行为——如果中间件里有 panic，测试会直接失败。

• 若中间件依赖全局变量（如数据库连接池），测试前需确保已初始化，或用接口抽象后注入 mock
• 测试 401/403 等拒绝响应时，检查 rr.Code 和 rr.Body.String() 是否符合预期，不要只看状态码
• 避免在中间件里调用 log.Fatal 或 os.Exit，这会让测试进程退出

func TestAuthMiddleware(t *testing.T) {
    // 构造带无效 token 的请求
    req := httptest.NewRequest("GET", "/admin", nil)
    req.Header.Set("Authorization", "Bearer invalid-token")
<pre class="brush:php;toolbar:false;">rr := httptest.NewRecorder()
// authMiddleware(justHandler) 是完整链
authMiddleware(justHandler).ServeHTTP(rr, req)

if rr.Code != http.StatusUnauthorized {
    t.Errorf("expected 401, got %d", rr.Code)
}
if !strings.Contains(rr.Body.String(), "invalid token") {
    t.Error("response body missing expected error message")
}

}

测试超时、重定向、客户端错误等边界情况

真实客户端行为（如取消请求、发送畸形 Body、不带必要 Header）很难靠单个 httptest.NewRequest 覆盖全。这时要分两层验证：

一是 handler 层：用 NewRequest 构造非法输入，确认它返回 400/415 等合理状态；二是服务层：用 NewServer 配合自定义 http.Client 控制超时、禁用重定向等。

• 测试超时：创建 client 设置 Timeout: 1 * time.Millisecond，再发请求，检查是否返回 context.DeadlineExceeded
• 测试重定向：client 默认跟随重定向，要测试原始 302 响应，需设 CheckRedirect: func(req *http.Request, via []*http.Request) error { return http.ErrUseLastResponse }
• 测试空 Body 或非 JSON：用 strings.NewReader("") 或 strings.NewReader("garbage")，验证 handler 是否正确返回 400

复杂点在于：有些错误发生在 net/http 底层（如 TLS 握手失败、DNS 解析超时），httptest 不模拟这些，只能靠集成测试加真实 stub 服务（如 gock）或跳过。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Golang如何测试REST接口详解》文章吧，也可关注golang学习网公众号了解相关技术文章。