Go net.Resolver.LookupHost 怎样带上下文解析主机地址

我在服务发现代码里第一次把主机名解析放进请求链路时，最容易忽略的不是 DNS 语法，而是“这次解析到底能等多久、返回了几个地址、失败属于哪一类”。如果直接调用包级 net.LookupHost，它内部使用的是 context.Background()，上游请求取消时无法把这个边界传进去。

结论：需要把解析绑定到请求生命周期时，使用 net.Resolver.LookupHost(ctx, host)。它返回 []string 和 error：成功时要准备好多个地址，超时或取消时要区分上下文错误，名称解析失败则按 DNS 错误处理。

官方地址：https://pkg.go.dev/net#Resolver.LookupHost

LookupHost 返回的到底是什么

Resolver.LookupHost 的签名是 func (r *Resolver) LookupHost(ctx context.Context, host string) (addrs []string, err error)。第一个返回值是地址字符串切片，不是一个只能保存单个 IPv4 的字段；同一个主机可能返回 IPv4、IPv6 或多个地址。第二个返回值负责表达解析是否完成，以及失败发生在哪一层。

最小调用可以这样写：

package main

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

func main() {
    ctx := context.Background()
    resolver := net.Resolver{}

    // LookupHost 返回所有可用的地址字符串，不能只按一个地址处理。
    addrs, err := resolver.LookupHost(ctx, "example.com")
    if err != nil {
        // 失败时保留原始错误，交给上层决定重试、降级或记录。
        fmt.Println("lookup failed:", err)
        return
    }

    // 逐个使用地址，避免丢掉多地址解析结果。
    for _, addr := range addrs {
        fmt.Println(addr)
    }
}

这里使用的是零值 net.Resolver。如果不需要单独控制解析器，也可以使用 net.DefaultResolver；关键是调用方法版本，把 ctx 显式传入。

把上下文当作解析请求的安全边界

我更愿意把 DNS 解析看成请求链路中的一个外部依赖：它消耗等待预算，也可能在上游已经结束后才返回。如果上游已经有上下文，就继续向下传；如果这是独立任务，再创建一个明确的超时上下文。

func resolveWithTimeout(parent context.Context, host string) ([]string, error) {
    // 超时只约束本次解析，避免 DNS 等待吞掉整个请求的剩余预算。
    ctx, cancel := context.WithTimeout(parent, 2*time.Second)
    defer cancel()

    resolver := net.Resolver{}
    // 将同一个 ctx 传给 LookupHost，使取消信号能到达解析调用。
    return resolver.LookupHost(ctx, host)
}

上面的示例还需要导入 time。生产代码中不要为了“保险”在每一层都重新套一个很长的超时；如果 parent 已经有更短的期限，子上下文不会把它放宽。解析的预算应当服从调用方的剩余时间。

成功、取消和 DNS 失败要分开记录

解析失败后不要只打印一条“lookup failed”就结束。对调用方来说，超时通常意味着应缩短任务、重试或走备用地址；DNS 错误则说明名称、配置或解析链路本身可能有问题。可以先用 errors.Is 判断上下文错误，再按需展开 *net.DNSError 的信息。

func resolveHost(ctx context.Context, host string) ([]string, error) {
    resolver := net.Resolver{}
    addrs, err := resolver.LookupHost(ctx, host)
    if err == nil {
        return addrs, nil
    }

    // 先识别调用方主动取消或超时，避免误报成 DNS 故障。
    if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
        return nil, fmt.Errorf("resolve %q stopped by context: %w", host, err)
    }

    var dnsErr *net.DNSError
    if errors.As(err, &dnsErr) {
        // DNSError 可用于记录 Name、Err、Timeout 等排障字段。
        return nil, fmt.Errorf("resolve %q failed: %w", host, dnsErr)
    }

    // 保留未知错误，避免把其他系统错误伪装成 DNS 错误。
    return nil, fmt.Errorf("resolve %q: %w", host, err)
}

这里的重点是错误分类顺序，而不是把所有错误都转换成自定义字符串。使用 %w 包装后，上层仍然可以用 errors.Is 或 errors.As 继续判断。

不要把地址字符串和 IP 对象混为一谈

LookupHost 适合“我需要拿到主机对应的地址字符串，再交给后续连接逻辑”的场景。如果调用方要明确限制 IPv4 或 IPv6，LookupIP 的 network 参数更直接；如果需要现代的 net/netip 地址类型，可考虑 LookupNetIP。这不是谁更快的问题，而是返回值是否匹配后续接口。

如果只是为了把结果交给 net.Dial，还要在拼接端口时正确处理 IPv6，不要手工拼出 addr + ":" + port。使用 net.JoinHostPort 能避免 IPv6 地址中的冒号破坏地址格式。

我现在会先检查这四个边界

• 输入：传入的是主机名还是已经解析好的字面量地址，是否包含意外的空格或端口。
• 期限：使用的是上游 ctx 还是包级函数，调用链取消后解析是否还能继续挂着。
• 结果：代码是否遍历 []string，是否错误地只取第一个地址并丢失备用地址。
• 错误：是否把 context.DeadlineExceeded、context.Canceled 和 *net.DNSError 记录成不同事件。

我的经验是，先把这四项写进代码评审清单，比一开始就调整解析器配置更有效。只有当返回形状、取消边界和错误语义都清楚后，才值得进一步讨论环境 DNS、重试或缓存策略。

常见问题

为什么不直接用 net.LookupHost？

包级函数适合不需要自定义上下文的简单调用，但它内部使用 context.Background()。服务请求、任务队列或命令行超时场景更适合使用 Resolver.LookupHost(ctx, host)。

LookupHost 会只返回一个地址吗？

不会。它返回地址字符串切片，代码应按多个地址设计；如果业务确实只允许某一类地址，应在 API 选择或结果处理处明确限制。

超时是不是一定代表域名不存在？

不是。超时说明本次请求的上下文期限耗尽，域名不存在、解析器拒绝或其他 DNS 故障应从 *net.DNSError 等错误信息中进一步区分。

小结

带上下文解析主机地址的关键写法只有一句：resolver.LookupHost(ctx, host)。真正决定代码是否可靠的是后面的三个动作：按 []string 处理多地址，沿用上游上下文控制等待边界，以及把上下文终止和 DNS 失败分开判断。这样做，服务发现和网络诊断才不会把取消请求误报成 DNS 故障，也不会因为只保留一个地址而失去后备路径。