Go net.DNSError Timeout 怎样判断 DNS 查询是否真的超时

我在给 DNS 失败做重试分类时，最容易踩的坑就是把 net.DNSError.Timeout() 当成了“这次网络请求到底有没有超时”的绝对答案。它真正回答的是：标准库是否知道这次失败属于超时。实用做法是先沿错误链找到 *net.DNSError，再把已知超时、未找到记录和普通失败分开处理。

官方文档：https://pkg.go.dev/net@go1.27.3#DNSError.Timeout

下面的代码和图都是静态说明，不代表本文在本机执行过具体 DNS 查询。

先把调用方真正需要的结果拆开

DNSError 记录了名称、服务器、底层错误和若干状态。Timeout() 返回 true 时，可以把错误归为“已知超时”；返回 false 时，还可能是名称不存在、记录类型没有数据、服务端拒绝，或者库没有掌握足够信息。它不是网络探针，也不是对 DNS 服务可用性的完整结论。

尤其要注意，文档明确提醒：一次查询即使因为超时失败，返回的 DNSError 也可能没有把 Timeout() 标记为 true。因此日志中应保留原始错误文本和目标名称，不要只保存一个布尔值。

让错误链承担类型定位

DNS 错误经常被 net.OpError 或业务层包装。如果直接写 err.(*net.DNSError)，只在错误恰好处于最外层时成立。更稳妥的方式是使用 errors.As，让标准库沿可展开的错误链寻找目标类型。

package dnscheck

import (
    "errors"
    "fmt"
    "net"
)

// classifyDNSError 只做错误分类，不负责决定是否重试。
func classifyDNSError(err error) string {
    if err == nil {
        return "ok"
    }

    var dnsErr *net.DNSError
    // errors.As 能穿过 OpError 或 fmt.Errorf 的 %w 包装。
    if !errors.As(err, &dnsErr) {
        return "non-dns-error"
    }
    if dnsErr.Timeout() {
        return "dns-timeout-known"
    }
    if dnsErr.IsNotFound {
        return "dns-name-or-record-not-found"
    }
    // 保留 Error 文本，避免把未知原因误报成超时。
    return fmt.Sprintf("dns-other: %s", dnsErr.Error())
}

这里把“分类”和“重试决策”分开：分类函数只提供稳定标签，调用方再根据请求是否幂等、备用解析器是否可用、用户是否能接受降级来决定动作。这样不会因为某个组件复用了分类函数，就把所有 DNS 错误都变成无限重试。

把 Timeout 放进完整的错误模型

如果调用的是 net.Resolver 或 net.LookupHost，上层还可能设置了 context 截止时间。上下文结束、连接拨号超时和 DNS 服务器响应超时并不一定会以完全相同的具体类型出现。判断 DNS 错误时，可以优先尝试 errors.As；判断整个请求是否超过了业务截止时间，则应另外考虑上下文错误或其包装。

// classifyLookupError 将 DNS 状态与调用范围分开记录。
func classifyLookupError(err error) (kind string, retryable bool) {
    if err == nil {
        return "ok", false
    }

    var dnsErr *net.DNSError
    if errors.As(err, &dnsErr) {
        if dnsErr.Timeout() {
            // 已知 DNS 超时，是否重试仍由上层策略决定。
            return "dns-timeout-known", true
        }
        if dnsErr.IsNotFound {
            return "dns-not-found", false
        }
        return "dns-error-uncertain", false
    }
    // 非 DNS 错误不应伪装成 DNS 超时。
    return "other-error", false
}

示例中的 retryable 只是业务策略演示，不是 Timeout() 的官方承诺。实际系统还要给重试设置次数、退避和总截止时间；如果错误类型无法确认，宁可保留原始错误并进入人工或监控分析，也不要依靠猜测扩大重试流量。

用一张表保留排障结论

最终可以记住三点：先用 errors.As 找到错误对象；再把 Timeout() 当作“已知超时”信号；最后结合 IsNotFound、上下文和业务截止时间决定重试。这样既能识别明确的 DNS 超时，也能保留标准库对不确定情况的诚实表达。

为什么不能直接把所有 DNS error 都重试？

名称不存在、记录类型没有数据和配置错误都可能持续失败，盲目重试只会增加等待时间和解析压力。先区分 Timeout() 与 IsNotFound，再结合业务幂等性决定策略。

Timeout() 返回 false 就代表没有发生超时吗？

不代表。它只说明当前错误对象没有被标准库明确标记为已知超时；官方文档也说明，部分超时场景的标记可能未知。

错误已经被 fmt.Errorf 包装怎么办？

使用 fmt.Errorf("lookup failed: %w", err) 保留错误链，并用 errors.As 查找 *net.DNSError；不要用只检查最外层的类型断言。