Go测试构造请求，httptest使用详解

本文深入解析了 Go 语言中使用 `httptest` 进行 HTTP 测试的核心技巧与常见陷阱：从正确构造测试请求（确保 URL 含协议、body 显式处理、Content-Type 设置）到精准捕获响应（利用 `NewRecorder` 断言状态码、Header 和 Body），再到还原真实调用链路（通过 `NewServer` 验证路由、中间件和框架行为），同时揭示了请求体不可重放、外部依赖未隔离等极易被忽视却导致测试脆弱或失效的关键问题——掌握这些，才能写出稳定、可维护且真正覆盖生产行为的 Go Web 测试。

怎么用 httptest.NewRequest 构造测试请求

构造请求是 httptest 最基础也最容易出错的一步。很多人直接传空字符串或忽略 method 和 url 格式，导致后续 handler 解析失败。

关键点：URL 必须带协议和路径（哪怕只是测试用），body 需要显式设置为 nil 或 io.Reader，不能传字符串字面量。

• httptest.NewRequest("GET", "http://example.com/api/users", nil) —— 正确，协议 + 路径 + 空 body
• httptest.NewRequest("POST", "/api/users", strings.NewReader(`{"name":"a"}`)) —— POST 带 JSON body，注意设好 Content-Type
• 漏掉 req.Header.Set("Content-Type", "application/json") → handler 可能跳过 JSON 解析
• 用 "localhost:8080/path" 当 URL → req.URL 解析失败，req.Host 为空，影响路由匹配

如何让 handler 正确处理测试请求

构造完 *http.Request 后，直接丢给 handler 是不够的。handler 通常依赖 http.ResponseWriter 的具体行为（比如写状态码、header、body），而真实响应器在测试中不可用。

httptest.NewRecorder() 就是为此设计的：它实现了 http.ResponseWriter 接口，把所有写入缓存在内存里，方便断言。

• 调用顺序必须是：req := httptest.NewRequest(...); w := httptest.NewRecorder(); handler.ServeHTTP(w, req)
• 别用 http.Response 或自定义 struct 替代 *httptest.ResponseRecorder，否则拿不到 w.Code、w.Body.String()
• 如果 handler 内部调用了 http.Redirect，检查 w.Header().Get("Location") 和 w.Code == http.StatusFound
• 注意 w.Body.Bytes() 和 w.Body.String() 的区别：后者会尝试 UTF-8 解码，遇到非法字节可能 panic

为什么测试时路由不生效？

直接调用某个 handler 函数（如 usersHandler(w, req)）绕过了路由层，自然不会触发 http.ServeMux 或 gorilla/mux 的路径匹配、中间件等逻辑。

要测完整链路，得把 handler 放进实际的 server 实例里跑，而不是单测函数。

• 用 http.NewServeMux() 注册路由后，传给 httptest.NewServer(mux) → 返回一个带真实地址的 *httptest.Server
• 然后用 http.Get(server.URL + "/api/users") 发请求，走完整 HTTP 栈（含 net/http transport）
• 更轻量的做法：用 server := httptest.NewServer(http.HandlerFunc(yourHandler))，适合只测单个 endpoint
• 若用 gin、echo 等框架，优先用它们自带的 test helper（如 gin.CreateTestContext），而非硬套 httptest

常见错误：Body 读取后无法重放

HTTP 请求体（req.Body）是单次读取的 io.ReadCloser。测试中如果 handler 多次调用 io.ReadAll(req.Body) 或先解析 JSON 再读原始 body，第二次就读不到内容了。

这不是 httptest 的 bug，而是 Go HTTP 的设计使然。测试时必须模拟可重放的 body。

• 构造请求时用 bytes.NewBufferString(jsonStr) 替代 strings.NewReader，前者支持 Seek(0, 0)
• 或者在 handler 开头加一句：bodyBytes, _ := io.ReadAll(r.Body); r.Body = io.NopCloser(bytes.NewBuffer(bodyBytes))
• 更稳妥的方式：测试前就用 ioutil.NopCloser 包一层可重放的 reader（Go 1.16+ 用 io.NopCloser）
• 忘记 req.Body.Close() 不会导致 panic，但属于资源泄漏习惯，测试里也建议补上

真正麻烦的不是怎么写测试，而是当 handler 依赖外部服务（DB、Redis、第三方 API）时，httptest 本身不解决依赖隔离——那得靠 interface 抽象 + mock，或者用 net/http/httptest 搭配 gock 拦截 outbound 请求。这部分容易被忽略，但一旦漏掉，测试就从单元测试滑向了集成测试。

今天关于《Go测试构造请求，httptest使用详解》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！