Golang API测试教程：httptest接口示例

net/http/httptest 是轻量级HTTP测试工具，NewRecorder用于服务端handler单元测试，NewServer用于客户端集成测试；应直接调用handler.ServeHTTP而非ListenAndServe以保证测试隔离性。

Go 的 net/http/httptest 是专为测试 HTTP 处理逻辑设计的轻量级工具，它不走网络栈、不依赖端口、不启动真实服务器，直接在内存中模拟请求-响应流程。只要你的 handler 符合 http.Handler 接口（即有 func(http.ResponseWriter, *http.Request) 签名），就能用它测。

用 httptest.NewServer 还是 httptest.NewRecorder？

二者用途完全不同，选错会导致测试写不下去或测不到关键路径：

• httptest.NewServer 启动一个真实监听的本地 HTTP 服务（绑定随机空闲端口），适合测试「客户端代码」——比如你封装了一个 apiClient.Do() 方法，需要发真实 HTTP 请求过去；
• httptest.NewRecorder 不起服务，只构造一个可读写的响应缓冲区（*httptest.ResponseRecorder），适合测试「服务端 handler 逻辑」——比如验证路由是否匹配、状态码是否正确、JSON 响应体是否符合预期。

绝大多数接口逻辑单元测试，应该用 NewRecorder。用 NewServer 属于集成测试范畴，启动慢、端口可能被占、需手动调用 .Close()，没必要。

测试带路径参数和查询参数的 handler

Go 的 http.Request 需要手动设置 URL.Path 和 URL.RawQuery，不能只靠字符串拼接 URL——否则 chi、gorilla/mux 等路由器无法正确解析路径参数（如 /users/{id}）。

正确做法是先构造 *http.Request，再通过 context.WithValue 或中间件注入路由参数（取决于你用的路由库），或直接使用对应 router 提供的测试辅助方法（如 chi.TestRequest）。但最通用、不依赖第三方的方式是：

• 用 http.NewRequest 创建基础请求；
• 手动设置 req.URL.Path 和 req.URL.RawQuery；
• 若 handler 依赖 http.Request.Context() 中的路由变量（如 chi 的 chi.URLParam(req, "id")），需用该 router 的测试工具初始化请求。

示例（纯 net/http 路由，无第三方框架）：

req, _ := http.NewRequest("GET", "/api/users/123?limit=10", nil)
req.URL.Path = "/api/users/123"
req.URL.RawQuery = "limit=10"
rr := httptest.NewRecorder()
handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    id := strings.TrimPrefix(r.URL.Path, "/api/users/")
    limit := r.URL.Query().Get("limit")
    json.NewEncoder(w).Encode(map[string]interface{}{"id": id, "limit": limit})
})
handler.ServeHTTP(rr, req)

测试 JSON 响应体和状态码时容易漏掉的点

很多人只检查 rr.Code，却忘了 rr.Body 是个 *bytes.Buffer，必须用 rr.Body.Bytes() 或 rr.Body.String() 读取内容；且 JSON 响应通常未格式化，直接用字符串比较易失败。

• 状态码必须显式断言：if rr.Code != http.StatusOK { t.Fatalf("expected 200, got %d", rr.Code) }；
• 响应体建议用 json.Unmarshal 解析后比对字段，而不是字符串匹配；
• 注意 handler 是否调用了 http.Error 或 w.WriteHeader —— 若 handler 内部 panic，rr.Code 默认是 200，需配合 recover 测试或使用 testify/assert 的 panics 断言；
• 若 handler 设置了自定义 Header（如 w.Header().Set("Content-Type", "application/json")），记得用 rr.Header().Get("Content-Type") 检查。

为什么测试中调用 handler.ServeHTTP(rr, req) 而不是 http.ListenAndServe？

因为 ServeHTTP 是 http.Handler 接口的方法，它把请求直接“推”给 handler 执行，跳过整个 HTTP 服务器启动、连接 Accept、TLS 握手等环节。这是单元测试的核心前提：隔离被测逻辑，排除环境干扰。

一旦你写了 http.ListenAndServe(":8080", handler) 并在测试里去 http.Get("http://localhost:8080/...")，就不再是单元测试，而是端到端测试——会受端口占用、防火墙、DNS 解析、超时设置等外部因素影响，且无法覆盖 handler 内部 panic、中间件短路等边界情况。

真正难测的，往往不是 handler 本身，而是它依赖的 service 层（如数据库、缓存、第三方 API）。这时候应该用 interface + mock，而不是把 httptest 当万能胶水去包住整个系统。