Go HTTP 客户端：http.Client 与请求配置

Go 语言内置的 net/http 包不仅提供了强大的 Web 服务器功能，同样包含了一个功能完善的 HTTP 客户端。默认情况下，直接使用 http.Get 或 http.Post 可以满足简单的请求需求，但在生产环境中，为了控制超时、重用连接、管理代理等，必须直接使用 http.Client 结构体并进行精细化配置。

以下指南将详细讲解如何配置和使用 Go 的 HTTP 客户端。

基础配置：创建自定义 Client

默认的 http.DefaultClient 没有设置超时时间，这在生产环境中是极其危险的，可能导致请求永久阻塞。创建一个自定义的 http.Client 是第一步。

定义 http.Client 结构体，并设置 Timeout 字段。

package main

import (
    "net/http"
    "time"
)

func main() {
    // 创建自定义 Client
    client := &http.Client{
        // 设置整个请求的总超时时间（包括连接、重定向、读取响应体）
        Timeout: 10 * time.Second,
    }

    // 使用 client 发起请求（此处仅展示结构，实际需配合 Request 使用）
    // resp, err := client.Get("https://example.com")
}

在这个配置中，Timeout 涵盖了从发起请求到读取完响应体的整个时间段。一旦超过该时间，请求会自动取消并报错。

进阶配置：Transport 与连接池

http.Client 的核心在于其 Transport 字段（类型为 http.RoundTripper）。默认情况下，Go 使用 http.DefaultTransport，它维护了一个连接池。为了适应高并发或特殊网络环境，需要自定义 Transport。

1. 配置连接池参数

直接修改 http.Transport 的字段来控制最大空闲连接数和每个主机的最大空闲连接数。

package main

import (
    "net/http"
    "time"
)

func main() {
    transport := &http.Transport{
        // Proxy: http.ProxyFromEnvironment, // 默认使用环境变量代理

        // DialContext: 自定义连接拨号逻辑（通常保留默认即可）

        // MaxIdleConns 控制最大空闲连接数（针对所有主机）
        MaxIdleConns: 100,

        // MaxIdleConnsPerHost 控制每个目标主机的最大空闲连接数
        // 默认值是 2，对于高并发场景通常需要调大
        MaxIdleConnsPerHost: 10,

        // IdleConnTimeout 空闲连接在连接池中的存活时间
        IdleConnTimeout: 90 * time.Second,

        // TLSHandshakeTimeout TLS 握手超时时间
        TLSHandshakeTimeout: 10 * time.Second,

        // ExpectContinueTimeout 在发送 100 Continue 状态码后的等待时间
        ExpectContinueTimeout: 1 * time.Second,
    }

    client := &http.Client{
        Transport: transport,
        Timeout:   30 * time.Second,
    }
}

注意：如果 MaxIdleConnsPerHost 设置过小，在并发请求同一个域名时，客户端会频繁建立 TCP 连接（三次握手），导致性能下降。根据并发量调整此参数是优化的关键。

2. 理解请求生命周期

当调用 client.Do(req) 时，内部流程如下所示。理解此流程有助于排查连接泄露或超时问题。

请求控制：使用 Context 实现精细化超时

虽然 Client.Timeout 可以设置总超时，但更灵活的方式是使用 context.Context。通过 Context，可以实现单次请求的独立超时控制，或者手动取消请求。

创建带有超时的 Context，并使用 http.NewRequestWithContext 构建请求。

package main

import (
    "context"
    "fmt"
    "net/http"
    "time"
)

func main() {
    client := &http.Client{
        Timeout: 30 * time.Second, // Client 级别的兜底超时
    }

    // 创建一个 2 秒后会自动取消的 Context
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel() // 确保在函数退出时释放资源

    // 创建 Request 并绑定 Context
    req, err := http.NewRequestWithContext(ctx, "GET", "https://httpbin.org/delay/5", nil)
    if err != nil {
        panic(err)
    }

    // 发起请求
    resp, err := client.Do(req)
    if err != nil {
        // 通常会报错：context deadline exceeded
        fmt.Printf("请求失败: %v\n", err)
        return
    }
    defer resp.Body.Close()

    fmt.Printf("请求状态码: %d\n", resp.StatusCode)
}

在上述代码中，即使 Client 的 Timeout 设置为 30 秒，因为 Context 设置了 2 秒超时，请求会在 2 秒时立即失败。这种方式在处理多个外部服务调用时非常有用，可以避免慢速服务拖垮整个程序。

高级配置：重定向策略

默认情况下，Client 会自动跟随重定向（最多跟随 10 次）。如果需要控制重定向行为，例如不跟随重定向或记录重定向路径，可以设置 CheckRedirect 字段。

以下代码展示如何停止自动重定向，并从响应头中获取重定向地址。

package main

import (
    "fmt"
    "net/http"
)

func main() {
    client := &http.Client{
        // 设置 CheckRedirect 函数
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            // 返回 http.ErrUseLastResponse 告知 Client 不要重定向，直接返回响应
            return http.ErrUseLastResponse
        },
    }

    resp, err := client.Get("https://httpbin.org/redirect/1")
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    // 状态码通常为 301 或 302
    fmt.Printf("状态码: %d\n", resp.StatusCode)
    // 获取重定向的目标地址
    fmt.Printf("跳转地址: %s\n", resp.Header.Get("Location"))
}

via 参数包含了之前所有请求的切片。如果访问 len(via) >= 10，可以自定义错误来打破默认的重定向次数限制。

常见配置参数速查表

下表列出了 http.Client 和 http.Transport 中最常用的配置项及其说明。

完整示例：生产级 Client 封装

结合上述配置，封装一个通用的 HTTP 客户端函数。

package main

import (
    "context"
    "io"
    "net/http"
    "time"
)

// NewClient 创建一个配置合理的 HTTP Client
func NewClient() *http.Client {
    transport := &http.Transport{
        MaxIdleConns:          100,
        MaxIdleConnsPerHost:   20,
        IdleConnTimeout:       90 * time.Second,
        TLSHandshakeTimeout:   10 * time.Second,
        ExpectContinueTimeout: 1 * time.Second,
    }

    return &http.Client{
        Transport: transport,
        Timeout:   30 * time.Second,
    }
}

// FetchContent 发起 GET 请求并返回内容
func FetchContent(ctx context.Context, url string) ([]byte, error) {
    client := NewClient()

    // 使用传入的 Context 创建 Request
    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
    if err != nil {
        return nil, err
    }

    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    // 读取响应体
    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }

    return body, nil
}

func main() {
    // 模拟使用
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    data, err := FetchContent(ctx, "https://www.google.com")
    if err != nil {
        // 处理错误
        panic(err)
    }

    // 使用 data...
    _ = data
}