Go net.Dialer Timeout 和 Deadline 该如何分别设置

我第一次把拨号超时从配置里抽出来时，最容易混淆的就是 Timeout 和 Deadline：前者像“给这次拨号多少秒”，后者却是“最晚不能超过哪个时刻”。在 Go 的 net.Dialer 中，二者都存在时不是相加，而是取更早的截止点；如果再传入带截止时间的 Context，还要继续取三者中的最早值。

需要固定连接预算时优先用 Timeout；需要让拨号服从整条请求链的绝对时间点时设置 Deadline 或使用 DialContext。生产代码通常让 Context 负责请求级截止，Dialer 的 Timeout 负责连接级兜底。

Timeout 和 Deadline 先别混：一个是时长，一个是时刻

Timeout: 3 * time.Second 不需要知道当前时间，表示从本次拨号开始最多等待三秒；Deadline: time.Now().Add(3 * time.Second) 则把一个绝对时刻交给拨号器。Deadline 适合多个动作共享同一条时间线，Timeout 更适合表达“单次建立连接最多花多久”。

这里有一个很实用的判断：如果 Deadline 已经过期，哪怕 Timeout 还剩十秒，拨号也不能继续；反过来，如果 Timeout 更短，也会先由 Timeout 触发。把模型记成“Timeout、Deadline 与 Context 共同指向最早截止时间”就不容易错。不要把 time.Duration 直接赋给 Deadline，后者的类型是 time.Time。

用 DialContext 把连接预算接到请求边界

我更常用下面这种写法：调用方给出请求 Context，Dialer 再提供一个连接级上限。这样上层取消、下游超时和拨号自身过慢都能结束同一次调用。

package main

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

func dialWithBudget(ctx context.Context, address string) (net.Conn, error) {
    // Timeout 只负责限制建立连接本身，避免底层网络无限等待。
    dialer := net.Dialer{Timeout: 3 * time.Second}
    // DialContext 会同时听从 ctx 的取消和截止时间。
    conn, err := dialer.DialContext(ctx, "tcp", address)
    if err != nil {
        return nil, fmt.Errorf("连接 %s 失败: %w", address, err)
    }
    return conn, nil
}

func main() {
    // 请求总预算比连接预算短时，Context 会更早结束拨号。
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel() // 释放定时器资源，调用方负责关闭连接。
    conn, err := dialWithBudget(ctx, "example.com:443")
    if err != nil {
        return
    }
    defer conn.Close() // 连接只在示例作用域内使用，退出前关闭。
}

如果业务已有统一的请求截止时间，不要在每层都重新 context.WithTimeout，否则日志里看到的“3 秒”可能只是某一层的局部数字。把请求级 Context 传到底层，Dialer 的 Timeout 只做合理兜底，排查会清楚很多。

多地址拨号时，Timeout 不是每个 IP 都重新拥有一份

TCP 地址使用主机名时，解析结果可能包含多个 IPv4 或 IPv6 地址。Go 会在连接尝试之间分配整体拨号预算，因此配置三秒并不等于“第一个地址三秒、第二个地址再三秒”。这也是为什么网络环境偶尔切换 IPv4/IPv6 时，实际每个地址的等待时间会比直觉更短。

超时之后看错误：先判断取消来源，再决定是否重试

不要看到“超时”就立刻重试。先判断 Context 是否已经结束，再看错误是否实现了 net.Error 且 Timeout() 返回真；如果是调用方主动取消，重试只会放大请求压力。

func classifyDialError(ctx context.Context, err error) string {
    // 先识别上游取消，避免把用户主动结束误判成网络抖动。
    if errors.Is(ctx.Err(), context.Canceled) {
        return "caller-canceled"
    }
    if errors.Is(ctx.Err(), context.DeadlineExceeded) {
        return "request-deadline"
    }
    // net.Error 只说明网络错误属性，仍要结合业务决定是否重试。
    var netErr net.Error
    if errors.As(err, &netErr) && netErr.Timeout() {
        return "dial-timeout"
    }
    return "other-network-error"
}

上面的示例需要在文件导入区增加 errors。实际项目中建议把地址、阶段和剩余预算写入结构化日志，不要只记录一行“连接超时”。排查时可以把 Context、错误链、net.Error 的 Timeout 方法、多地址解析和整体拨号预算看成一组输入，最后再作重试决策。

常见问题

Timeout 和 Deadline 可以同时设置吗？

可以。它们不会叠加，谁对应的截止点更早谁生效；若 Context 还有更早截止，也以 Context 为准。

只用 net.DialTimeout 够不够？

单次、独立拨号可以；如果拨号属于请求链，优先用 DialContext，让上游取消和截止时间能够传到底层。

连接建立成功后 Context 到期会关闭连接吗？

不会。Context 只影响 DialContext 完成前的拨号过程；连接建立后是否关闭、读写是否超时，要另行管理连接生命周期和读写 Deadline。