Go context HTTP 超时 区分 deadline 与 transport timeout

Go HTTP 超时最容易误判的地方，是把 context deadline、http.Client.Timeout 和 Transport 的阶段超时当成同一件事。它们都可能让 client.Do 返回超时错误，但约束范围和排查入口不同。

实用的判断顺序是：先看请求是否绑定了带 deadline 的 context，再看错误链能否匹配 context.DeadlineExceeded，最后结合 net.Error.Timeout() 判断是否属于网络传输层超时。Client.Timeout 更像一次请求的总预算；ResponseHeaderTimeout、拨号超时和 TLS 握手超时则只约束传输中的某个阶段。

先把三类超时放回各自边界

context.WithTimeout 或 context.WithDeadline 产生的是请求可以携带的截止时间。只要把它绑定到 http.Request，底层传输就能感知取消；如果请求仍然使用 context.Background()，你在外层创建的 context 不会自动影响它。

http.Client.Timeout 覆盖一次客户端请求的总时间，包括连接、重定向和读取响应体。它适合给调用方设置一个硬上限，但不适合替代所有阶段参数，因为它无法直接告诉你究竟卡在拨号、TLS、响应头还是响应体。

http.Transport 则提供更细的阶段控制。例如 net.Dialer.Timeout 限制建立连接，TLSHandshakeTimeout 限制 TLS 握手，ResponseHeaderTimeout 限制请求写完后等待响应头的时间。它们是静态的传输边界，不代表完整业务超时。

这些边界可以叠加。实际生效的总时间通常不会超过最先到期的那个限制，所以不要把每个数字简单相加后当作客户端必然可用的时间。

把 deadline 绑定到 Request，而不是只包住调用函数

下面的最小写法把调用方 context 派生为一个有时限的 context，并通过 http.NewRequestWithContext 绑定到请求。代码没有依赖错误字符串，后面可以继续沿错误链判断原因。

package main

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

func getWithDeadline(parent context.Context, client *http.Client, target string) error {
    // 派生 deadline，并在函数返回时释放计时器等 context 资源。
    ctx, cancel := context.WithTimeout(parent, 1200*time.Millisecond)
    defer cancel()

    // 只有绑定到 Request 的 context 才会进入 net/http 请求链。
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, target, nil)
    if err != nil {
        return fmt.Errorf("创建请求失败: %w", err)
    }

    resp, err := client.Do(req)
    if err != nil {
        // 不匹配错误文本，优先检查 context 是否因 deadline 到期而结束。
        if errors.Is(err, context.DeadlineExceeded) {
            return fmt.Errorf("请求触发 context deadline: %w", err)
        }
        return fmt.Errorf("HTTP 请求失败: %w", err)
    }
    // Do 成功返回后，响应体由调用方负责关闭。
    defer resp.Body.Close()

    if resp.StatusCode = http.StatusMultipleChoices {
        return fmt.Errorf("远端返回状态码 %d", resp.StatusCode)
    }
    return nil
}

这里的 defer cancel() 不是为了“强行终止所有工作”，而是释放派生 context 的计时器，并通知仍在使用该 context 的可取消操作。拿到响应后安排 Body.Close 是另一项职责，两者不能互相替代。

用错误链判断：到底是谁先超时

client.Do 返回的错误通常会包在 *url.Error 中。可以用 errors.Is 检查它是否包含 context.DeadlineExceeded，也可以通过 errors.As 取出实现了 net.Error 的错误并调用 Timeout()。这比判断“timeout”字符串稳定。

func classifyHTTPError(err error) string {
    if err == nil {
        return "没有错误"
    }

    // context deadline 说明请求上下文的截止时间先结束了。
    if errors.Is(err, context.DeadlineExceeded) {
        return "context deadline 超时"
    }

    var netErr net.Error
    // net.Error.Timeout 说明错误属于网络层的超时语义，但仍需结合阶段日志判断位置。
    if errors.As(err, &netErr) && netErr.Timeout() {
        return "transport 阶段超时"
    }
    return "其他 HTTP 错误"
}

上面的片段需要在文件导入区加入 net。它刻意把“判断错误”和“决定是否重试”分开：Timeout() 只能说明错误具有超时语义，不能单独证明请求一定安全可重试。POST 请求是否已被服务端接收、请求体是否可重放，都要另行判断。

为 Transport 配置阶段超时，避免只剩一个总开关

当排查重点是连接建立或响应头迟迟不来，可以把阶段参数配置在可复用的 Transport 上。http.Client 和 Transport 通常应复用，而不是每次请求重新创建。

func newHTTPClient() *http.Client {
    // 拨号器只限制建立连接，不覆盖后续读取响应体。
    dialer := &net.Dialer{Timeout: 400 * time.Millisecond}
    transport := &http.Transport{
        // 连接建立慢时尽早返回，避免占住调用 goroutine。
        DialContext: dialer.DialContext,
        // TLS 握手单独设置上限，便于从日志中区分连接和协商问题。
        TLSHandshakeTimeout: 500 * time.Millisecond,
        // 请求写完后等待响应头的时间，不包含读取响应体的时间。
        ResponseHeaderTimeout: 800 * time.Millisecond,
    }
    return &http.Client{
        // 总预算兜底，覆盖连接、重定向和响应体读取。
        Timeout: 1500 * time.Millisecond,
        Transport: transport,
    }
}

这个组合的含义是：阶段超时负责给具体网络环节设边界，Client.Timeout 负责兜底，Request context 负责承接上游取消和业务 deadline。三者并不是“谁更高级”的替代关系。

有 Response 时先清理，再决定是否重试

当 Do 返回错误时，通常直接处理错误；当它返回非空 Response 时，必须关闭 Response.Body。响应体没有读完、也没有关闭，可能影响连接复用并长期占住资源。

func closeResponse(resp *http.Response) error {
    if resp == nil || resp.Body == nil {
        return nil
    }
    // Body 的所有权在拿到 Response 后转给调用方，关闭动作不能省略。
    defer resp.Body.Close()

    // 只读取有限大小，避免为了连接复用而无限等待或吃光内存。
    _, err := io.CopyN(io.Discard, resp.Body, 64*1024)
    if err != nil && !errors.Is(err, io.EOF) {
        return fmt.Errorf("读取响应体失败: %w", err)
    }
    return nil
}

是否读取剩余响应体要看场景：小响应、短连接探活可以有限度消费；大响应、流式响应或已到达 deadline 时，关闭和退出通常比等待读完更重要。重试前还要确认方法、请求体和服务端副作用符合重试条件，不能因为错误带有 timeout 就盲目重发。

排查清单：从 deadline 到 transport timeout

1. 确认 http.NewRequestWithContext 或 req.WithContext 使用的是带 deadline 的 context，而不是另一个 Background()。
2. 记录请求开始时间、目标主机和阶段性错误；不要只记录 err.Error() 后再用字符串分类。
3. 用 errors.Is(err, context.DeadlineExceeded) 判断 context deadline，再用 errors.As 检查 net.Error.Timeout()。
4. 检查 DialContext、TLSHandshakeTimeout、ResponseHeaderTimeout 和 Client.Timeout 是否互相覆盖或过短。
5. 确认拿到非空 response 后总会关闭 Body，并确认重试逻辑不会重复提交不可重放的请求。

最后可以把规则压缩成一句话：deadline 解决“这项工作最晚什么时候结束”，transport timeout 解决“网络的某一段最多等多久”；错误链负责告诉你哪类边界先触发，Response.Body 则始终由调用方清理。

常见问题

只设置 Client.Timeout，还需要 context.WithTimeout 吗？

如果调用方还需要在用户取消、上游请求结束或多个下游共享同一截止时间时主动终止工作，仍然需要 Request context。Client.Timeout 可以作为单次 HTTP 调用的总预算兜底，两者职责不同。

errors.Is 能判断所有 transport timeout 吗？

它适合判断错误链中是否包含特定 sentinel，例如 context.DeadlineExceeded。传输层的具体错误可能包裹在 *url.Error 中，更通用的做法是用 errors.As 提取 net.Error，再结合日志判断发生阶段。

请求超时后还要关闭 Response.Body 吗？

如果 Do 已经返回了非空 Response，就按调用方责任关闭 Body；如果只有 error 且没有 Response，则不要凭空解引用 Body。始终先判断返回值，再安排清理。