Go http.Client 请求超时为什么没有按预期结束怎样构造最小复现

如果 Go 的 http.Client 请求“超时了却没有按预期结束”，先看两个事实：零值 Timeout 表示不设客户端总超时；已经拿到响应头后，后续读取 Response.Body 仍属于超时范围。最容易定位的方法，是用 httptest 让服务端故意延迟响应头，再观察 Do 返回的错误。

先判断：你设置的是总超时，还是根本没有超时

我遇到这类问题时，第一眼会找创建 Client 的地方，而不是先修改重试逻辑。http.Client 的 Timeout 默认值是零，官方语义是“没有超时”；零值 Client 仍然可用，但网络异常时可能长时间等待。http.Get 使用的是 DefaultClient，如果没有统一初始化它，同样不会自动得到一个业务超时。

另一个容易混淆的点是“请求函数返回”和“请求生命周期结束”不是同一个瞬间。Do 拿到响应头后会返回 Response，但响应体是按需读取的；如果服务端持续发送慢数据，后面的 io.ReadAll 仍可能在超时点被打断。代码应把读取和关闭 Body 放在同一个错误处理路径里：

client := &http.Client{Timeout: 2 * time.Second}

resp, err := client.Get(url)
if err != nil {
    // 超时、建连失败和重定向失败都先处理，不能继续使用 resp。
    var urlErr *url.Error
    if errors.As(err, &urlErr) && urlErr.Timeout() {
        return fmt.Errorf("请求超时: %w", err)
    }
    return fmt.Errorf("请求失败: %w", err)
}
defer resp.Body.Close() // 成功拿到响应后，读取完成也要释放连接资源。

用延迟响应头构造一个稳定的最小复现

不要拿不稳定的公网地址测试超时。下面的服务端在写响应头前等待 300 毫秒，客户端只给 80 毫秒，因此每次都能把“等待响应头”与“业务代码没有结束”区分开。这是静态示例，重点是控制延迟位置，而不是伪造线上运行截图。

package main

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

func main() {
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 故意延迟响应头，复现客户端等待服务器首字节的场景。
        time.Sleep(300 * time.Millisecond)
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte("ok"))
    }))
    defer server.Close() // 测试结束后关闭监听器，避免资源泄漏。

    client := &http.Client{Timeout: 80 * time.Millisecond}
    started := time.Now()
    resp, err := client.Get(server.URL)
    if err != nil {
        // 这里通常会得到带有 Client.Timeout 语义的 *url.Error。
        fmt.Printf("elapsed=%s timeout=%v err=%v\n", time.Since(started), true, err)
        return
    }
    defer resp.Body.Close() // 只有 err 为 nil 时才读取并关闭响应体。
    fmt.Println("status:", resp.Status)
}

复现时不要把输出中的耗时当成精确基准，调度和机器负载会带来少量波动；要观察的是错误发生在客户端预算内，并且服务端仍可能尚未写出响应头。官方文档还说明，非 2xx 状态本身不会让 Do 返回错误，超时应从 err 和 *url.Error 的 Timeout() 判断。

单次请求要更短：把预算放进 Request.Context

Client.Timeout 适合给同一个 Client 设置兜底上限；如果某个接口的预算不同，给请求绑定 context 更直观。请求 context 控制连接、发送请求、等待响应头以及读取响应体的整个生命周期，因此它能把“拿到响应后还在读 Body”的情况一起收住。

func fetch(ctx context.Context, client *http.Client, endpoint string) ([]byte, error) {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
    if err != nil {
        // URL 不合法时在发请求前返回，调用方可以直接修正配置。
        return nil, fmt.Errorf("创建请求: %w", err)
    }

    resp, err := client.Do(req)
    if err != nil {
        // Context 到期、客户端总超时和网络错误都在这里汇合。
        return nil, fmt.Errorf("发送请求: %w", err)
    }
    defer resp.Body.Close() // Body 读取结束后释放可复用的连接。

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        // 响应头已到达并不代表响应体一定完整到达。
        return nil, fmt.Errorf("读取响应体: %w", err)
    }
    if resp.StatusCode = 300 {
        // HTTP 状态错误与网络错误分开，便于上层选择是否重试。
        return nil, fmt.Errorf("HTTP 状态异常: %s", resp.Status)
    }
    return body, nil
}

ctx, cancel := context.WithTimeout(context.Background(), 120*time.Millisecond)
defer cancel() // 即使提前返回也释放计时器关联的资源。
body, err := fetch(ctx, &http.Client{}, "https://api.example.test/data")
_ = body
_ = err

几个看似超时、实际不是超时的坑

如果代码给 Client 设置了 2 秒，又给 Request 设置了 100 毫秒，实际截止时间取更早者；这不是“两个超时叠加成 2.1 秒”。排查时记录请求阶段和错误包装即可，不要只打印一行“timeout”。

常见问题

为什么设置了 Client.Timeout，服务端仍然可能收到请求？

客户端超时控制的是本地请求生命周期，不是撤销已经到达服务端的业务副作用。服务端是否停止处理，还要看它是否读取并响应请求 context，以及业务是否可取消。

只用 context.WithTimeout 还需要 Client.Timeout 吗？

单次请求可以只用 context；共享 Client 时通常还会保留一个较长的 Client.Timeout 作为兜底，避免调用方漏传 context 时出现无限等待。

怎样确认是等待响应头还是读取响应体超时？

把测试服务的延迟分别放在写响应头之前和分段写 Body 之间：前者观察 Do 返回错误，后者观察 io.ReadAll 返回错误。两种错误都应保留原始错误链，便于用 errors.Is 或 url.Error.Timeout() 判断。