Go HTTP 客户端超时的 DNS 连接与响应分层

Go HTTP 客户端出现超时，先不要直接把 http.Client.Timeout 调大。一次请求至少可以拆成 DNS 解析、TCP 连接、TLS 握手、等待响应头和读取响应体几个阶段；不同阶段对应的控制点不同，只有先分层，错误才有机会被解释。

可以先记住这条结论：Client.Timeout 负责整次请求的总截止时间；请求上下文负责当前调用的取消；Transport 的 DialContext、TLSHandshakeTimeout 和 ResponseHeaderTimeout 负责连接建立过程中的细分阶段。它们不是互相替代的同名开关。

先把一次请求拆成五个阶段

当 URL 使用域名时，客户端首先要把主机名解析为 IP；随后尝试建立 TCP 连接。HTTPS 还要进行 TLS 握手，连接建立后才会发送或等待 HTTP 数据。服务端返回响应头后，响应体仍可能持续很久，流式接口就是典型场景。

因此，“连接超时”和“响应超时”不是一回事。DNS 慢时，服务端甚至还没有看到请求；响应头慢时，连接已经建立，但服务端还没有给出可判断状态码的头部；响应体慢时，响应头可能早已返回，只是后续读取没有结束。

区分 Client.Timeout 与请求上下文

Client.Timeout 会覆盖连接时间、重定向以及读取响应体的时间，而且在 Do 返回后读取 Response.Body 时仍然可能中断。它适合表达“这个请求最多占用多少时间”的业务上限。

请求上下文更适合表达一次调用的取消来源，例如上游请求结束、用户主动取消或本次调用的截止时间。两者同时存在时，较早到达的取消会先生效。下面的代码只展示配置关系；其中的中文注释说明了每个时间值的责任。

package main

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

func doRequest(parent context.Context, url string) error {
    // Context 表达单次调用的业务截止时间，应该由调用方负责取消。
    ctx, cancel := context.WithTimeout(parent, 4*time.Second)
    defer cancel()

    // Client.Timeout 是整次请求的硬上限，也会覆盖响应体读取阶段。
    client := &http.Client{Timeout: 6 * time.Second}
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return fmt.Errorf("创建请求失败: %w", err)
    }

    resp, err := client.Do(req)
    if err != nil {
        return fmt.Errorf("请求失败: %w", err)
    }
    defer resp.Body.Close() // 关闭响应体，避免连接资源无法回收。
    return nil
}

这个例子中，4 秒的上下文会先于 6 秒的客户端总超时生效。不要把 Client.Timeout 误认为只限制“等待响应头”；如果响应头已经返回但响应体读取迟迟没有结束，它仍然会影响后续读取。

用 DialContext 定位 DNS 与 TCP 连接

Transport.DialContext 是创建未加密 TCP 连接的入口。它接收请求上下文，因此 DNS 或拨号阶段可以随着上下文取消。底层使用 net.Dialer.DialContext 时，Dialer.Timeout 表示拨号等待连接完成的时间，而不是整次 HTTP 请求的总预算。

生产配置中可以把拨号器和 Transport 分开写出来，便于日志中明确标识“拨号阶段”：

dialer := &net.Dialer{
    Timeout:   2 * time.Second,  // DNS/拨号预算，超时后返回连接错误。
    KeepAlive: 30 * time.Second, // 连接建立后的 TCP 保活参数，不是请求超时。
}

transport := &http.Transport{
    DialContext:          dialer.DialContext, // 让拨号遵循请求 Context。
    TLSHandshakeTimeout:  2 * time.Second,   // 仅限制 HTTPS 握手等待。
    ResponseHeaderTimeout: 3 * time.Second,  // 请求写完后等待响应头的上限。
}

client := &http.Client{
    Transport: transport,
    Timeout:   6 * time.Second, // 最外层总预算，覆盖响应体读取。
}

要注意，连接池复用成功连接时，当前请求可能不会重新经历 DNS 和 TCP 拨号；因此不要把每一次请求都强行解释为“做了一次 DNS”。只有实际建立新连接时，拨号阶段才会执行。

给 TLS 和响应头设置阶段上限

HTTPS 连接可能已经完成 DNS 和 TCP，但 TLS 握手仍然卡住。此时看起来像“连接超时”，实际应该检查 TLSHandshakeTimeout。它只约束 TLS 握手等待，设置为零表示不限制该阶段。

ResponseHeaderTimeout 的起点也很明确：请求已经完整写出后，等待服务端响应头的时间。它不包括继续读取响应体的时间，所以不适合用来限制下载或流式读取；这类总预算仍要由上下文或 Client.Timeout 表达。

如果请求使用 Expect: 100-continue，还可以关注 ExpectContinueTimeout，但它只处理等待服务端首个响应头的特定阶段，不要把它当成普通 GET 请求的通用响应超时。

用 httptrace 记录阶段时间

只打印 err.Error() 往往无法判断到底慢在解析、连接、握手还是服务端响应。net/http/httptrace 可以为单次请求挂接回调，把关键阶段的时间点写入日志。下面的代码使用相对时间，避免把真实地址或响应内容写进日志。

start := time.Now()
trace := &httptrace.ClientTrace{
    DNSStart: func(info httptrace.DNSStartInfo) {
        fmt.Printf("dns start host=%s at=%s\n", info.Host, time.Since(start)) // 记录解析开始。
    },
    DNSDone: func(info httptrace.DNSDoneInfo) {
        fmt.Printf("dns done addrs=%d err=%v at=%s\n", len(info.Addrs), info.Err, time.Since(start)) // 只记数量和错误。
    },
    ConnectStart: func(network, addr string) {
        fmt.Printf("connect start network=%s at=%s\n", network, time.Since(start)) // 不记录完整地址，减少日志敏感信息。
    },
    ConnectDone: func(network, addr string, err error) {
        fmt.Printf("connect done network=%s err=%v at=%s\n", network, err, time.Since(start)) // 判断 TCP 是否完成。
    },
    GotConn: func(info httptrace.GotConnInfo) {
        fmt.Printf("got conn reused=%t at=%s\n", info.Reused, time.Since(start)) // 区分连接复用与新建。
    },
}

ctx := httptrace.WithClientTrace(context.Background(), trace)
req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
    return err
}
resp, err := client.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close()

如果日志只有 DNSStart 没有 DNSDone，优先看解析上下文是否结束；如果已经 GotConn 仍迟迟没有响应头，则问题已经越过 DNS 和 TCP，应该检查服务端处理或响应头等待预算。

整理成可复用的分层配置

一个容易解释的配置顺序是：先给单次调用设定业务截止时间，再用 Transport 约束连接建立和响应头等待，最后用 Client 总超时兜底。时间值不是固定答案，要根据上游 SLA、网络环境、请求体大小和是否流式响应来调整。

func newHTTPClient() *http.Client {
    dialer := &net.Dialer{
        Timeout:   2 * time.Second,  // 只给新连接的 DNS/拨号阶段预算。
        KeepAlive: 30 * time.Second, // 连接保活，不等于 HTTP 请求期限。
    }
    transport := &http.Transport{
        DialContext:          dialer.DialContext,
        TLSHandshakeTimeout:  2 * time.Second, // HTTPS 握手上限。
        ResponseHeaderTimeout: 3 * time.Second, // 等响应头上限，不管响应体。
    }
    return &http.Client{
        Transport: transport,
        Timeout:   8 * time.Second, // 兜底总预算，覆盖重定向和响应体读取。
    }
}

Transport 应该复用，而不是每次请求都创建；它内部维护连接缓存，并且可以并发使用。响应成功后仍要关闭 Body，需要读取内容时也要由调用方明确决定是否读到 EOF。

常见误区

• 把所有错误都叫“DNS 超时”：只有请求还在解析或拨号阶段时，才应沿着 DialContext 方向排查。
• 只设置 ResponseHeaderTimeout：它不限制响应体读取，下载和流式接口仍需要上下文或总超时。
• 每次请求都新建 Transport：连接池无法稳定复用，反而可能放大连接建立压力。
• 只保存错误字符串：应该记录 url.Error 的底层错误和阶段时间，但不要把完整请求头、令牌或响应体写入日志。
• 看到 Client.Timeout exceeded 就继续加大时长：先用 httptrace 看是否卡在 DNS、连接、握手、响应头或响应体。

速查表

相关问题

http.Client.Timeout 会不会限制响应体读取？

会。它覆盖连接、重定向和响应体读取，并可能在 Do 返回后继续影响读取。

ResponseHeaderTimeout 能限制下载时间吗？

不能。它只等待响应头，响应体读取需要单独的上下文或总超时策略。

连接复用时还会发生 DNS 超时吗？

复用已有连接时通常不会重新执行该次拨号流程。判断是否新建连接，可以用 httptrace.GotConn 的 Reused 信息辅助分析。