Go net.Resolver.LookupAddr 反向解析失败时怎么处理多个 PTR 结果

在访问日志里给客户端 IP 补主机名时，最容易踩到的误区是把反向解析当成“一个 IP 对应一个字符串”。net.Resolver.LookupAddr 的返回值其实是 []string，同一个地址可能带回多个 PTR 名称；解析器还可能在返回部分名称的同时给出错误。

官方资料：https://pkg.go.dev/net#Resolver.LookupAddr

稳妥的处理方式是：先用 net.ParseIP 判断输入，使用带超时的 Resolver.LookupAddr，无论 names 是否为空都先保留它，再根据错误类型决定记录、重试还是降级。下面按一次“日志里的主机名偶尔为空”的排查过程拆开说明。

一、先看清 LookupAddr 的返回契约

现场代码通常写成 names, err := resolver.LookupAddr(ctx, addr)，然后只要 err != nil 就返回空主机名。这个判断太早了：API 返回的是名称列表，文档也明确说明，响应里有格式非法的名称时，合法名称会被保留，同时返回错误。

因此要先接受三个事实：一是 len(names) 可能大于 1；二是 len(names) > 0 与 err != nil 可以同时成立；三是完全没有名称和“有名称但伴随错误”不是同一件事。

二、先规范输入地址并设置超时

反向查询入口不要直接接受任意日志字符串。LookupAddr 接收的是地址文本，先过滤明显非法的输入，既能减少无意义的 DNS 请求，也能把“输入问题”和“解析问题”分开记录。

package reverse

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

// lookupPTR 为一次反向查询设置边界，并保留解析器返回的全部名称。
func lookupPTR(parent context.Context, addr string) ([]string, error) {
    // ParseIP 只负责判断文本是否像 IP，不会发起 DNS 请求。
    if net.ParseIP(addr) == nil {
        return nil, fmt.Errorf("invalid IP address %q", addr)
    }

    ctx, cancel := context.WithTimeout(parent, 2*time.Second)
    defer cancel() // 查询结束后及时释放定时器和取消链。

    // Resolver.LookupAddr 返回名称切片；不要在这里把多个名称压成一个值。
    return net.DefaultResolver.LookupAddr(ctx, addr)
}

这里没有把地址解析成 net.IP 后再传回去，因为 API 的参数类型就是字符串；ParseIP 只作为入口检查。超时也应属于调用边界的一部分，避免日志处理协程无限等待 DNS。

三、同时保留部分 PTR 结果和错误

修复现场问题时，第一处改动不是“忽略 error”，而是调整返回结构，让调用方能同时看到可用名称和错误原因。可以把结果包装成一个明确的值对象：

type PTRResult struct {
    Address string
    Names   []string
    Err     error
}

// resolvePTR 让上层决定如何展示部分结果，而不是在底层偷偷丢弃。
func resolvePTR(ctx context.Context, addr string) PTRResult {
    names, err := lookupPTR(ctx, addr)
    return PTRResult{
        Address: addr,
        Names:   append([]string(nil), names...), // 复制切片，避免后续复用造成数据串写。
        Err:     err,
    }
}

如果返回两个名称和一个错误，日志可以先显示两个名称，再把错误作为独立字段；如果名称为空，才把主机名展示为未解析。不要用 names[0] 代表“官方主机名”，因为多个 PTR 的顺序不应该被业务逻辑当成稳定优先级。

四、按错误类型决定记录、重试还是降级

排查到这里，下一步是把错误分类，而不是把所有非空 error 都判成同一种失败。不同错误的处理动作可以保持简单：

func describePTR(result PTRResult) string {
    names := normalizeNames(result.Names)
    if result.Err == nil {
        return fmt.Sprintf("addr=%s ptr=%v status=ok", result.Address, names)
    }

    // 有部分结果时仍输出它们；错误单独保留，方便后续判断是否重试。
    if len(names) > 0 {
        return fmt.Sprintf("addr=%s ptr=%v status=partial err=%v", result.Address, names, result.Err)
    }
    return fmt.Sprintf("addr=%s ptr=[] status=unresolved err=%v", result.Address, result.Err)
}

这里的 status=partial 是应用层语义，不是 DNS 标准状态码。它的价值在于让日志消费者知道：这个地址并非完全没有结果，也不应把错误字段简单覆盖掉。

五、把结果变成稳定的日志字段

多个 PTR 结果还会带来重复、名称末尾点和输出顺序的问题。日志系统如果直接打印原始切片，后续聚合可能把同一组名称识别成不同值。可以在展示层做轻量整理：

func normalizeNames(input []string) []string {
    seen := make(map[string]struct{}, len(input))
    out := make([]string, 0, len(input))
    for _, name := range input {
        // DNS 展示名常以根域点结束；去掉它只用于日志展示，不修改查询语义。
        name = strings.TrimSuffix(strings.TrimSpace(name), ".")
        if name == "" {
            continue
        }
        if _, ok := seen[name]; ok {
            continue
        }
        seen[name] = struct{}{}
        out = append(out, name)
    }
    sort.Strings(out) // 输出稳定，便于日志聚合和测试断言。
    return out
}

上面的函数需要补充 strings 和 sort 导入。去掉末尾点是展示策略，不代表 DNS 名称本身没有根标签；如果业务要做严格比较，应保留原始名称或明确统一规范。

六、用可控 Resolver 做复查

如果排查结果只在某台机器上成立，别急着把它归因于 Go 代码。标准库文档说明，名称解析会受操作系统和 resolver 选择影响；默认解析器在不同环境里可能走不同实现。诊断代码至少要保留输入地址、超时、名称列表和错误，不要只打印最终的第一个名称。

func checkOne(ctx context.Context, resolver *net.Resolver, addr string) PTRResult {
    if net.ParseIP(addr) == nil {
        return PTRResult{Address: addr, Err: fmt.Errorf("invalid IP")}
    }

    // 复查时沿用调用方 context，便于测试主动取消。
    names, err := resolver.LookupAddr(ctx, addr)
    return PTRResult{
        Address: addr,
        Names:   append([]string(nil), names...),
        Err:     err,
    }
}

测试时可以注入自己的查询实现或在隔离环境中固定网络条件，但不要把某次机器上的 PTR 输出写死成业务规则。复查的目标是确认：输入校验有效、超时能结束、多个名称都被保留、部分结果不会被错误覆盖。

总结

net.Resolver.LookupAddr 的正确使用重点只有四个：把返回值当成名称切片；允许名称与错误同时存在；用 context 限制等待时间；在展示层再做去重和排序。这样，反向解析失败时不会丢掉可用的 PTR 信息，也不会把暂时超时、无记录和输入错误混成同一种空字符串。

常见追问

LookupAddr 为什么会返回多个名称？ PTR 记录可以为同一地址提供多个反向映射，调用方应遍历整个切片。

有 names 时还要处理 err 吗？ 要。错误可能表示结果不完整或存在格式问题，是否降级应由业务决定。

能不能只用 net.LookupAddr？ 可以做简单查询，但它内部使用背景 context；需要超时、取消或自定义 resolver 时应使用 Resolver.LookupAddr。