Go netip.Addr Is4In6 怎样识别 IPv4 映射地址

在双栈入口、反向代理或连接日志里，同一个 IPv4 可能以 192.0.2.10 出现，也可能写成 ::ffff:192.0.2.10。如果直接把后者当普通 IPv6，地址去重和来源判断就容易出现两套结果。Go 的 netip.Addr.Is4In6 就是用来识别这种 IPv4 映射 IPv6 地址的。

官方文档：https://pkg.go.dev/net/netip#Addr.Is4In6

Is4In6 判断地址是否位于 ::ffff:0:0/96；映射地址的 Is4() 返回 false，Is6() 返回 true。需要把它作为 IPv4 使用时，再调用 Unmap()。

先用 ParseAddr 得到可判断的 Addr

Is4In6 是 netip.Addr 的方法，不能直接对字符串调用。先用 netip.ParseAddr 解析，并把错误和地址分类放在同一个入口，后续业务就不必重复猜测字符串格式。

package main

import (
    "fmt"
    "net/netip"
)

func describe(text string) (string, error) {
    // 解析失败时不要把原始字符串当成合法地址继续传递。
    ip, err := netip.ParseAddr(text)
    if err != nil {
        return "invalid", err
    }

    // 映射地址先单独判断，避免被 Is6 的结果掩盖。
    switch {
    case ip.Is4In6():
        return "ipv4-mapped-ipv6", nil
    case ip.Is4():
        return "ipv4", nil
    case ip.Is6():
        return "ipv6", nil
    default:
        // ParseAddr 不会返回零 Addr，但保留兜底便于函数复用。
        return "invalid", nil
    }
}

func main() {
    kind, err := describe("::ffff:192.0.2.10")
    if err != nil {
        fmt.Println("解析失败:", err)
        return
    }
    fmt.Println(kind) // ipv4-mapped-ipv6
}

这里的判断顺序很重要：先看 Is4In6，再看 Is4 和 Is6。官方定义中，IPv4 映射 IPv6 仍然属于 IPv6，因此只写 if ip.Is6() 会把它和普通 IPv6 混在一起。

Is4In6、Is4 和 Is6 分别代表什么

可以把三个方法理解为不同层次的标签，而不是互相排斥的枚举值：

Is4() 专门表示内部地址就是 IPv4；文档明确说明它对 IPv4 映射 IPv6 返回 false。Is6() 则包含所有 IPv6 形态，包括映射地址。因此想识别映射关系，不能用 !ip.Is4() 代替 Is4In6()，因为普通 IPv6 也会满足前者。

用 Unmap 统一业务侧的地址键

识别出映射地址后，如果业务需要按“实际 IPv4”做限流、去重或审计，可以调用 Unmap()。它只对 IPv4 映射 IPv6 去掉映射前缀，返回原生 IPv4；普通 IPv6 则保持不变。

package main

import "net/netip"

func normalizedClientIP(text string) (netip.Addr, error) {
    // 先解析，确保返回值始终是已初始化的 Addr。
    ip, err := netip.ParseAddr(text)
    if err != nil {
        return netip.Addr{}, err
    }

    // Unmap 对原生 IPv4 和普通 IPv6 都是安全的原样返回。
    return ip.Unmap(), nil
}

func isMapped(text string) (bool, error) {
    // 分类和规范化分开，调用方可以保留原始形态用于日志。
    ip, err := netip.ParseAddr(text)
    if err != nil {
        return false, err
    }
    return ip.Is4In6(), nil
}

日志场景可以同时保存原始文本和 Unmap 后的规范化地址：前者帮助定位代理或协议边界，后者用于稳定的业务键。不要把所有非 Is4() 地址都强行转成 IPv4，否则普通 IPv6 会被错误处理。

落地时固定这四个判断边界

• 先解析再分类：解析错误应单独返回，不能把字符串前缀判断当作地址解析。
• 先识别映射地址：Is4In6 是最具体的判断，避免被 Is6 覆盖。
• 规范化要有目的：只有业务键需要统一时才调用 Unmap，原始地址仍可留在日志中。
• 零值不是未指定地址：netip.Addr{} 是无效零值；如果函数接收外部 Addr，可先用 IsValid() 判断。

这套写法的核心不是记住一个方法名，而是把“地址类型识别”和“业务侧规范化”拆开。Is4In6 回答地址是否属于 IPv4 映射 IPv6，Unmap 回答是否需要变成原生 IPv4；两个问题分开后，双栈输入就不会在日志、缓存键和权限判断中产生隐式差异。

常见问题

IPv4 映射 IPv6 用 Is6 判断会是什么结果？

会返回 true。映射地址仍按 IPv6 形态存储，所以需要额外调用 Is4In6 区分它。

Unmap 会把普通 IPv6 转成 IPv4 吗？

不会。只有 IPv4 映射 IPv6 会被转换，普通 IPv6 会原样返回。

可以用字符串是否包含 ::ffff: 来判断吗？

不建议。字符串可能有不同表示形式，应该先用 ParseAddr，再使用 Is4In6 的地址语义判断。