Go语言httptest使用全攻略

Go语言中的HTTP测试挑战与httptest简介

在Go语言开发中，应用程序常常需要与外部HTTP服务进行交互（作为客户端）或提供HTTP服务（作为服务器）。对这些HTTP相关的逻辑进行单元测试是确保代码质量和可靠性的关键。然而，直接依赖外部服务进行测试会带来诸多问题：测试环境不稳定、速度慢、数据难以控制、可能产生副作用等。

net/http/httptest包正是为了解决这些问题而设计的。它提供了两种核心机制，允许开发者在不启动真实HTTP服务器或不依赖外部服务的情况下，对HTTP客户端代码和HTTP处理函数进行高效、隔离的测试：

1. httptest.NewServer: 用于模拟一个完整的HTTP服务器，供HTTP客户端代码调用。
2. httptest.NewRecorder: 用于模拟一个HTTP响应写入器（http.ResponseWriter），捕获HTTP处理函数的输出。

接下来，我们将详细介绍这两种机制的使用方法。

使用httptest.NewServer测试HTTP客户端

当你的Go代码扮演HTTP客户端角色，需要向外部API发送请求并处理其响应时，httptest.NewServer是理想的测试工具。它会在本地启动一个临时的、可控的HTTP服务器，你的客户端代码可以向这个模拟服务器发送请求，而不是实际的外部服务。

核心原理

httptest.NewServer接收一个http.Handler（通常是一个http.HandlerFunc）作为参数，这个Handler定义了模拟服务器如何响应客户端的请求。服务器启动后，它会提供一个URL（server.URL），你的客户端代码可以将这个URL作为目标地址。

示例：测试一个获取推文的HTTP客户端

假设我们有一个函数，用于从某个Twitter API获取推文数据并解析JSON响应。为了便于测试，我们将原问题中的retrieveTweets函数进行简化，使其只执行一次请求并返回结果，同时将目标URL作为参数传入。

1. 客户端代码 (client.go)

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

// twitterResult 结构体用于解析Twitter API的JSON响应
type twitterResult struct {
    Results []struct {
        Text     string `json:"text"`
        Ids      string `json:"id_str"`
        Name     string `json:"from_user_name"`
        Username string `json:"from_user"`
        UserId   string `json:"from_user_id_str"`
    } `json:"results"` // 注意这里需要匹配JSON中的"results"键
}

// FetchTweets fetches tweets from a given URL and unmarshals them.
func FetchTweets(url string) (*twitterResult, error) {
    resp, err := http.Get(url)
    if err != nil {
        return nil, fmt.Errorf("HTTP GET failed: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("unexpected status code: %d", resp.StatusCode)
    }

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        return nil, fmt.Errorf("failed to read response body: %w", err)
    }

    r := new(twitterResult)
    // 如果r已经是指针类型，则无需再次取地址
    err = json.Unmarshal(body, r)
    if err != nil {
        return nil, fmt.Errorf("failed to unmarshal JSON: %w", err)
    }
    return r, nil
}

2. 测试代码 (client_test.go)

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
    "net/http/httptest"
    "strings"
    "testing"
)

// mockTwitterResponse 定义一个模拟的Twitter API JSON响应
var mockTwitterResponse = `{
    "results": [
        {"text":"Hello Go","id_str":"12345","from_user_name":"Tester","from_user":"go_tester","from_user_id_str":"67890"},
        {"text":"Learning httptest","id_str":"54321","from_user_name":"Dev","from_user":"go_dev","from_user_id_str":"09876"}
    ]
}`

func TestFetchTweets(t *testing.T) {
    // 1. 创建一个模拟服务器
    // 这个HandlerFunc定义了模拟服务器收到请求时如何响应
    handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 可以根据请求的路径、查询参数等来返回不同的响应
        if r.URL.Path != "/search.json" {
            http.Error(w, "Not Found", http.StatusNotFound)
            return
        }
        if r.URL.Query().Get("q") != "#GoLang" {
            http.Error(w, "Bad Request: Invalid query", http.StatusBadRequest)
            return
        }

        w.Header().Set("Content-Type", "application/json")
        fmt.Fprint(w, mockTwitterResponse) // 写入模拟的JSON响应
    })

    server := httptest.NewServer(handler)
    defer server.Close() // 确保测试结束后关闭模拟服务器

    // 2. 将客户端的目标URL指向模拟服务器的URL
    testURL := server.URL + "/search.json?q=%23GoLang"

    // 3. 调用被测试的客户端函数
    tweets, err := FetchTweets(testURL)
    if err != nil {
        t.Fatalf("FetchTweets returned an error: %v", err)
    }

    // 4. 验证返回的数据是否符合预期
    if tweets == nil {
        t.Fatal("Expected tweets, got nil")
    }
    if len(tweets.Results) != 2 {
        t.Errorf("Expected 2 tweets, got %d", len(tweets.Results))
    }

    expectedText0 := "Hello Go"
    if tweets.Results[0].Text != expectedText0 {
        t.Errorf("Expected first tweet text to be %q, got %q", expectedText0, tweets.Results[0].Text)
    }

    expectedUsername1 := "go_dev"
    if tweets.Results[1].Username != expectedUsername1 {
        t.Errorf("Expected second tweet username to be %q, got %q", expectedUsername1, tweets.Results[1].Username)
    }
}

// checkBody 是原问题中提供的辅助函数，用于检查响应体
func checkBody(t *testing.T, r *http.Response, expectedBody string) {
    b, err := ioutil.ReadAll(r.Body)
    if err != nil {
        t.Errorf("reading response body: %v", err)
        return
    }
    if g, w := strings.TrimSpace(string(b)), strings.TrimSpace(expectedBody); g != w {
        t.Errorf("request body mismatch: got %q, want %q", g, w)
    }
}

func TestFetchTweets_ErrorHandling(t *testing.T) {
    // 模拟服务器返回非200状态码
    handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        http.Error(w, "Internal Server Error", http.StatusInternalServerError)
    })
    server := httptest.NewServer(handler)
    defer server.Close()

    _, err := FetchTweets(server.URL)
    if err == nil {
        t.Fatal("Expected an error for non-200 status, got nil")
    }
    if !strings.Contains(err.Error(), "unexpected status code: 500") {
        t.Errorf("Expected error message to contain '500', got: %v", err)
    }
}

注意事项

• defer server.Close(): 这是至关重要的，它确保在测试函数结束时，模拟服务器会被正确关闭，释放端口和其他资源。
• URL配置: 客户端代码的URL应该可以通过参数、配置或全局变量进行修改，以便在测试中指向server.URL。
• Handler的灵活性: http.HandlerFunc内部可以实现复杂的逻辑，根据请求的Method、URL、Header或Body返回不同的模拟响应，甚至模拟网络延迟或错误。
• 并发测试: 如果你的客户端代码涉及并发请求，httptest.NewServer也能很好地支持，因为它是一个真实的HTTP服务器实例。

使用httptest.NewRecorder测试HTTP处理函数（Handler）

当你的Go代码作为HTTP服务器，需要测试http.Handler或http.HandlerFunc的业务逻辑时，httptest.NewRecorder是最佳选择。它允许你在不启动整个HTTP服务器栈的情况下，直接调用Handler，并捕获其产生的响应。

核心原理

httptest.NewRecorder实现了http.ResponseWriter接口，因此你可以将它作为参数传递给你的Handler的ServeHTTP方法。Handler会将响应头、状态码和响应体写入到这个Recorder中，测试代码随后可以检查Recorder的这些属性来验证Handler的行为。

示例：测试一个简单的API处理函数

假设我们有一个API端点/greeting，它接收GET请求并返回一个JSON格式的问候语。

1. 处理函数代码 (handler.go)

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

// GreetingResponse 定义问候语的JSON结构
type GreetingResponse struct {
    Message string `json:"message"`
    Status  string `json:"status"`
}

// GreetingHandler 处理 /greeting 路径的请求
func GreetingHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodGet {
        http.Error(w, "Method Not Allowed", http.StatusMethodNotAllowed)
        return
    }

    if r.URL.Path != "/greeting" {
        http.Error(w, "Not Found", http.StatusNotFound)
        return
    }

    resp := GreetingResponse{
        Message: "Hello from Go API!",
        Status:  "success",
    }

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(resp)
}

2. 测试代码 (handler_test.go)

package main

import (
    "encoding/json"
    "net/http"
    "net/http/httptest"
    "strings"
    "testing"
)

func TestGreetingHandler(t *testing.T) {
    // 1. 创建一个模拟请求
    // 第一个参数是HTTP方法，第二个是URL路径，第三个是请求体（GET请求通常为nil）
    req, err := http.NewRequest("GET", "/greeting", nil)
    if err != nil {
        t.Fatal(err)
    }

    // 2. 创建一个响应记录器
    rr := httptest.NewRecorder()

    // 3. 调用处理函数的ServeHTTP方法
    // 将模拟的响应记录器和请求传递给Handler
    GreetingHandler(rr, req)

    // 4. 验证响应状态码
    if status := rr.Code; status != http.StatusOK {
        t.Errorf("handler returned wrong status code: got %v want %v",
            status, http.StatusOK)
    }

    // 5. 验证响应头
    expectedContentType := "application/json"
    if contentType := rr.Header().Get("Content-Type"); contentType != expectedContentType {
        t.Errorf("handler returned wrong content-type: got %q want %q",
            contentType, expectedContentType)
    }

    // 6. 验证响应体
    expectedBody := `{"message":"Hello from Go API!","status":"success"}` + "\n" // json.Encoder会添加换行符
    if strings.TrimSpace(rr.Body.String()) != strings.TrimSpace(expectedBody) {
        t.Errorf("handler returned unexpected body: got %v want %v",
            rr.Body.String(), expectedBody)
    }

    // 也可以进一步解析JSON响应体进行验证
    var response GreetingResponse
    err = json.Unmarshal(rr.Body.Bytes(), &response)
    if err != nil {
        t.Fatalf("Failed to unmarshal response body: %v", err)
    }
    if response.Message != "Hello from Go API!" {
        t.Errorf("Expected message 'Hello from Go API!', got %q", response.Message)
    }
    if response.Status != "success" {
        t.Errorf("Expected status 'success', got %q", response.Status)
    }
}

func TestGreetingHandler_MethodNotAllowed(t *testing.T) {
    req, err := http.NewRequest("POST", "/greeting", nil) // 模拟POST请求
    if err != nil {
        t.Fatal(err)
    }
    rr := httptest.NewRecorder()
    GreetingHandler(rr, req)

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

func TestGreetingHandler_NotFound(t *testing.T) {
    req, err := http.NewRequest("GET", "/wrongpath", nil) // 模拟错误路径
    if err != nil {
        t.Fatal(err)
    }
    rr := httptest.NewRecorder()
    GreetingHandler(rr, req)

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

注意事项

• 直接调用: httptest.NewRecorder的优势在于可以直接调用Handler的ServeHTTP方法，无需启动监听端口，测试速度极快。
• 请求体: 如果Handler需要处理请求体（例如POST请求），可以通过http.NewRequest的第三个参数传入io.Reader。
• 中间件测试: 对于使用net/http标准库或如Gorilla Mux等路由库构建的中间件，也可以通过类似的方式进行测试，只需将整个Handler链传入ServeHTTP即可。

Go HTTP测试的最佳实践

为了编写高质量、可维护的HTTP测试，除了掌握httptest的基本用法外，还需要遵循一些最佳实践：

1. 解耦HTTP客户端逻辑: 将发送HTTP请求、处理响应、解析数据等逻辑封装在独立的函数或方法中，使其不依赖于具体的URL或http.Client实例。这样，在测试时可以方便地替换掉实际的依赖。
2. 配置化URL: 避免在代码中硬编码外部服务的URL。通过函数参数、结构体字段或环境变量