Go httptrace.DNSDone 怎样读取 DNS 阶段的错误

如果你想知道一次 Go HTTP 请求的 DNS 阶段到底发生了什么，重点看 httptrace.ClientTrace 的 DNSDone 回调。它在 DNS 查找结束时收到一个 httptrace.DNSDoneInfo：Addrs 表示查找到的 IPv4 或 IPv6 地址，Err 表示 DNS 查找错误，Coalesced 表示地址是否与同时进行同一查找的调用者共享。

这里最容易混淆的一点是：DNSDoneInfo.Err 只描述 DNS 这一层，不能替代最终的 RoundTrip 或 Client.Do 错误。排查时先记录 DNSDone，再结合最终请求错误下结论。

官方文档：https://pkg.go.dev/net/http/httptrace#ClientTrace.DNSDone

先分清 DNSDone 回调与最终请求错误

可以把一次请求拆成两个观察点：

因此，“DNSDone 没有错误”不等于请求一定成功；它只说明 DNS 这一段没有报告错误。反过来，DNSDone 报错时，最终请求错误通常还会带有更外层的上下文，应该两处都保留。

把 DNSDone 接到请求上下文

ClientTrace 通过请求上下文生效。下面的代码只给当前请求安装追踪钩子，不会改变解析器或连接策略。

package main

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

func newTracedRequest(ctx context.Context, target string) (*http.Request, error) {
    // 只观测 DNS 结束事件，不在回调中修改 Transport 配置。
    trace := &httptrace.ClientTrace{
        DNSDone: func(info httptrace.DNSDoneInfo) {
            // Err 描述 DNS 阶段；Addrs 只读，不能在回调里改写。
            fmt.Printf("dns addrs=%v err=%v coalesced=%v\\n", info.Addrs, info.Err, info.Coalesced)
        },
    }

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, target, nil)
    if err != nil {
        // URL 或请求参数错误还没有进入 DNS 阶段，直接返回。
        return nil, err
    }
    // 将 trace 放入请求上下文，Transport 才能触发 DNSDone。
    req = req.WithContext(httptrace.WithClientTrace(req.Context(), trace))
    return req, nil
}

如果请求 URL 本身无效，函数会在 DNS 之前返回错误，这种情况自然不会触发 DNSDone。这也是为什么最终请求错误不能只靠回调判断。

读取 Addrs、Err 与 Coalesced

三个字段分别对应三个不同问题：

• Addrs：查找到的 IPv4 和/或 IPv6 地址。它适合写入诊断日志，但不要对这个切片排序、追加或复用修改。
• Err：DNS 查找过程中出现的错误。判断 DNS 阶段是否失败时看它，而不是看地址数量。
• Coalesced：本次地址结果是否与另一个同时进行相同 DNS 查找的调用者共享。它是观测信息，不是错误标记。

不要把“地址列表为空”机械等同于“DNS 一定失败”。诊断日志应该同时保存 len(Addrs)、Err 和最终请求错误；真正的失败结论要结合具体 Transport 行为与请求结果。

func summarizeDNS(info httptrace.DNSDoneInfo) string {
    // 只读取字段，保留 Err 的原始错误文本用于后续关联。
    if info.Err != nil {
        return fmt.Sprintf("dns failed: addrs=%d err=%v shared=%t", len(info.Addrs), info.Err, info.Coalesced)
    }
    // 没有 DNS 错误时仍记录地址数量，便于和连接阶段日志对照。
    return fmt.Sprintf("dns ok: addrs=%d shared=%t", len(info.Addrs), info.Coalesced)
}

处理并发回调与空地址列表

ClientTrace 的回调可能从不同 goroutine 调用，也可能在请求已经完成或失败后才结束。若要把 DNS 结果写入共享诊断结构，应使用锁或 channel；不要在回调里直接追加共享切片。

type DNSRecord struct {
    Addrs     []string
    ErrText   string
    Coalesced bool
}

// copyDNSRecord 将回调数据复制到自己的记录中，避免持有只读切片。
func copyDNSRecord(info httptrace.DNSDoneInfo) DNSRecord {
    addrs := make([]string, 0, len(info.Addrs))
    for _, addr := range info.Addrs {
        // String 只做展示转换，不改变原始 IPAddr。
        addrs = append(addrs, addr.String())
    }
    record := DNSRecord{Addrs: addrs, Coalesced: info.Coalesced}
    if info.Err != nil {
        // 保留错误文本，避免把错误对象跨 goroutine 长期持有。
        record.ErrText = info.Err.Error()
    }
    return record
}

最终发送请求时仍要检查返回值。DNSDone 的结果适合回答“DNS 阶段发生了什么”，而 RoundTrip 或 Client.Do 的错误才适合回答“这次请求最终为什么没有完成”。

一张表记住排查顺序

这样记录，日志里即使只有一次失败，也能判断失败停在 DNS，还是已经进入连接、TLS 或响应处理阶段。

常见追问

DNSDone.Err 非空时还要看 RoundTrip error 吗？

要看。前者是 DNS 阶段错误，后者是整次请求的最终错误，保留两者更容易关联底层原因和上层上下文。

可以直接修改 DNSDoneInfo.Addrs 吗？

不可以。官方文档明确说明地址切片内容不应被修改；如果需要持久化或排序，先复制出自己的字符串切片。

Coalesced 为 true 是不是 DNS 失败？

不是。它表示查找结果与并发调用者共享，属于缓存或合并观测信息，不是错误状态。

为什么请求失败却没有进入 DNSDone？

请求可能在构造、代理选择、连接复用或其他阶段失败；同时，已有连接复用时也不一定发生新的 DNS 查找。要结合其他 ClientTrace 钩子和最终错误判断。

记住一句话：DNSDoneInfo.Err 解释 DNS，Addrs 解释 DNS 找到了什么，Coalesced 解释结果是否被并发共享，最终请求错误再负责收束整条链路。