Go netip.AddrFromSlice 处理 IPv4 映射 IPv6 的转换边界

把 net.IP 或网络报文中的地址字节交给 netip.AddrFromSlice 时，最容易混淆的是“长度合法”和“地址语义”并不是一回事。4 字节输入会得到 IPv4，16 字节输入会得到 IPv6；如果这 16 字节是 ::ffff:192.0.2.1 这样的 IPv4-mapped IPv6，返回值仍保留 IPv6 身份。需要统一成 IPv4 比较时，再显式调用 Unmap。

先按切片长度判断 AddrFromSlice 的输入边界

netip.AddrFromSlice 的契约很窄：长度为 4 按 IPv4 解析，长度为 16 按 IPv6 解析，其他长度直接返回 Addr{} 和 false。因此判断结果要同时接收地址与布尔值，不能只检查地址字符串。

这里还有一个边界：全零的 4 字节是有效的 0.0.0.0，全零的 16 字节是有效的 ::，它们都不是解析失败。真正的失败信号是 ok == false，不是“地址看起来特殊”。

区分 IPv4、原生 IPv6 与 IPv4-mapped IPv6

16 字节的 00 00 00 00 00 00 00 00 00 00 ff ff c0 00 02 01 表示 IPv4-mapped IPv6。AddrFromSlice 会忠实保留这层表示，所以打印时可能得到带 ::ffff: 前缀的地址。此时 addr.Is4() 只能说明它属于 IPv4 语义范围，不能告诉你它是否以 IPv4-mapped IPv6 形式进入；需要用 addr.Is4In6() 单独判断。

func parseAddr(raw []byte, normalizeMapped bool) (netip.Addr, bool) {
    addr, ok := netip.AddrFromSlice(raw)
    if !ok {
        return netip.Addr{}, false
    }
    if normalizeMapped {
        addr = addr.Unmap()
    }
    return addr, true
}

这个函数把“能不能解析”和“是否规范化”拆成两个决定。调用方如果还需要记录原始协议形态，就把 normalizeMapped 设为 false；如果要与只保存 IPv4 的白名单比较，则统一走 Unmap。

用 Unmap 统一比较和业务分支的地址语义

Unmap 只改变 IPv4-mapped IPv6 的表达方式：映射地址会变成普通 IPv4，原生 IPv4 保持不变，原生 IPv6 也保持不变。它适合放在“业务需要统一键空间”的边界，而不是无条件放在解析入口。

• 白名单或去重键：先决定是否把 192.0.2.1 与 ::ffff:192.0.2.1 视为同一主体，再对参与比较的值调用 Unmap。
• 日志与审计：若要保留代理链路或协议输入的真实形态，保存原始 Addr，另存规范化值，不要覆盖原字段。
• map key：netip.Addr 是可比较值，可以直接作为键；但同一业务若混用映射和非映射形式，仍会出现两个键。

把失败处理和转换策略收进边界函数

生产代码建议在输入层完成长度和 ok 检查，在业务层明确是否规范化。不要写成“解析失败就返回 netip.IPv4Unspecified()”，因为这样会把坏输入伪装成一个合法地址。也不要只用 Is4() 做分支，否则映射 IPv6 可能绕过你想要的兼容策略。

检查清单可以压缩成三项：第一，所有 4 或 16 以外的输入是否被拒绝；第二，比较前是否统一了 Unmap 规则；第三，日志是否仍保留了原始地址语义。这样既能避免零值误判，也能把协议表示和业务判断分开。

常见问题

AddrFromSlice 返回 false 时可以继续使用返回的 Addr 吗？

不可以。此时返回的是 Addr{}，应先返回输入错误或跳过当前记录；不要把它当成未指定地址。

调用 Unmap 会把所有 IPv6 地址变成 IPv4 吗？

不会。只有 IPv4-mapped IPv6 会被压回 IPv4，原生 IPv6 保持原样；这也是它适合放在白名单比较边界的原因。