Go net/netip 解析地址并区分 IPv4 映射

处理配置文件、代理头或访问日志中的 IP 文本时，我更愿意先把字符串转换成 netip.Addr，再做地址族判断和网段判断。这样做的关键不是把字符串换成另一种类型，而是把“原生 IPv4”“IPv4 映射 IPv6”“原生 IPv6”和“带 zone 的 IPv6”分开处理。

本文只围绕 ParseAddr、Prefix 和格式化展开：先解析地址，再识别 IPv4 映射，随后把 CIDR 前缀规范化，最后选择适合日志、比较或二进制接口的输出方式。

最稳妥的工作流是：ParseAddr 接收文本，Is4/Is4In6/Is6 判断类型，必要时调用 Unmap 归一化；网段输入用 ParsePrefix，需要网络地址时显式调用 Masked，成员判断交给 Contains。

目标和边界：先把“地址长什么样”说清楚

netip 的核心类型是值类型 Addr，它可以表示 IPv4、IPv6，也可以携带 IPv6 scope zone。和只拿字符串比较相比，Addr 能让后续代码直接调用类型判断方法；和旧式字节切片相比，它还是可比较的值，适合放进 map 或作为结构体字段。

本文不处理主机名解析，也不把端口和地址混在一起。输入是已经拿到的数值地址文本，例如 192.0.2.10、2001:db8::10 或带接口 zone 的链路本地地址。

全流程总览：解析、分类、归一化、输出四段走

一个可复用的地址处理函数可以拆成四段：

1. 解析：调用 netip.ParseAddr，错误直接返回，不让无效输入进入业务分支。
2. 分类：先问 Is4In6，再根据策略决定保留映射形式还是调用 Unmap。
3. 归一化：需要判断网段时用 ParsePrefix，需要展示网络起点时再调用 Masked。
4. 输出：日志优先用 String，追加到已有缓冲区用 AppendTo，协议字段再按需要使用 As4 或 As16。

这四段的顺序很重要：如果还没有决定映射地址的语义，就直接把所有 Is6 结果当作“原生 IPv6”，后面很容易出现分类或统计偏差。

解析阶段：ParseAddr 负责把文本变成 Addr

ParseAddr 接受点分十进制 IPv4、压缩写法 IPv6，以及带 scope zone 的 IPv6。它返回 (Addr, error)，生产代码应保留错误并附带输入来源；只有测试中的硬编码常量才适合使用 MustParseAddr。

package main

import (
    "fmt"
    "net/netip"
)

// parseInput 只负责解析，不在这里偷偷做 DNS 或端口拆分。
func parseInput(raw string) (netip.Addr, error) {
    addr, err := netip.ParseAddr(raw)
    if err != nil {
        // 把原始输入留在上层日志或错误上下文中，便于定位配置问题。
        return netip.Addr{}, fmt.Errorf("parse IP %q: %w", raw, err)
    }
    return addr, nil
}

解析失败时不要把零值 Addr{} 当成 0.0.0.0。官方文档明确区分了零值地址与 IPv4 unspecified 地址，因此错误路径应该通过 error 传递，而不是只检查 String() 的结果。

地址分类：用 Is4、Is4In6、Is6 和 Unmap 区分 IPv4 映射

这里最容易混淆的是：Is6 对 IPv4 映射 IPv6 也会返回 true，而 Is4 对映射形式返回 false。因此如果业务想把“IPv4 语义”统一统计，不能只写 if addr.Is4()。

package main

import "net/netip"

type AddressKind string

const (
    KindIPv4      AddressKind = "ipv4"
    KindIPv4In6   AddressKind = "ipv4-mapped-ipv6"
    KindIPv6      AddressKind = "ipv6"
)

// classifyAddr 先识别映射形式，避免被 Is6 的结果覆盖语义。
func classifyAddr(addr netip.Addr) (AddressKind, bool) {
    if !addr.IsValid() {
        return "", false
    }
    if addr.Is4In6() {
        return KindIPv4In6, true
    }
    if addr.Is4() {
        return KindIPv4, true
    }
    if addr.Is6() {
        return KindIPv6, true
    }
    return "", false
}

// canonicalIPv4 只在业务决定“映射地址按 IPv4 处理”时调用 Unmap。
func canonicalIPv4(addr netip.Addr) netip.Addr {
    if addr.Is4In6() {
        return addr.Unmap()
    }
    return addr
}

保留映射形式适合记录协议层输入；归一化为 IPv4 则适合做 IPv4 白名单、统计或 key 设计。不要无条件调用 Unmap 后再声称输入始终是“原生 IPv4”，因为这会丢掉“它最初以 IPv4 映射 IPv6 形式出现”的信息。

网段阶段：用 ParsePrefix、Masked 和 Contains 组织 CIDR 判断

ParsePrefix 读取类似 192.0.2.10/24 或 2001:db8::/32 的 CIDR。它返回的前缀会保留输入地址的未屏蔽位，所以展示网络起点时应显式调用 Masked；判断某个地址是否属于网段时，直接调用 Contains 更清楚。

package main

import (
    "fmt"
    "net/netip"
)

// inPrefix 只把前缀解析和成员判断放在同一个小函数里，便于复用错误语义。
func inPrefix(rawPrefix, rawAddr string) (bool, string, error) {
    prefix, err := netip.ParsePrefix(rawPrefix)
    if err != nil {
        return false, "", fmt.Errorf("parse prefix %q: %w", rawPrefix, err)
    }
    addr, err := netip.ParseAddr(rawAddr)
    if err != nil {
        return false, "", fmt.Errorf("parse address %q: %w", rawAddr, err)
    }

    // Masked 得到网段起点；Contains 负责判断地址是否属于同一前缀。
    network := prefix.Masked()
    return prefix.Contains(addr), network.String(), nil
}

还要注意地址族边界：IPv4 地址不会匹配 IPv6 前缀，IPv4 映射 IPv6 也不会自动匹配 IPv4 前缀。如果系统的输入允许两种形式，需要先按业务策略归一化，再决定用哪一种前缀参与判断。

输出阶段：String、AppendTo 与 As4/As16 怎么选

展示地址时优先使用 String，它表达的是可读的文本形式；已有缓冲区时可以用 AppendTo，避免为了拼接日志反复创建中间字符串。需要固定字节宽度时才用 As4 或 As16，并先确认地址族，否则错误输入会触发 panic。

package main

import (
    "fmt"
    "net/netip"
)

// formatAddr 根据用途选择可读文本或固定字节表示。
func formatAddr(addr netip.Addr) string {
    if !addr.IsValid() {
        return ""
    }
    if addr.Is4() {
        // As4 只对原生 IPv4 或映射地址安全；这里已限定为原生 IPv4。
        octets := addr.As4()
        return fmt.Sprintf("%d.%d.%d.%d", octets[0], octets[1], octets[2], octets[3])
    }

    // String 保留 IPv6 的规范文本形式与可能存在的 zone。
    return addr.String()
}

// appendAddr 适合把地址追加到已有日志缓冲区。
func appendAddr(dst []byte, addr netip.Addr) []byte {
    // AppendTo 复用调用方的容量，不改变 Addr 本身。
    return addr.AppendTo(dst)
}

As16 会把 IPv4 表示成 IPv4-mapped IPv6 的 16 字节形式，因此它适合固定宽度协议或哈希输入，却不适合直接用来判断“原始输入是不是 IPv6”。格式化前先明确数据用途，可以避免把显示格式和比较格式混在一起。

推荐流程：把地址处理收敛成可检查的边界

在真实代码中，可以把策略固定成下面的检查顺序：一是输入不通过 ParseAddr 就停止；二是记录 Is4In6 结果，再决定是否 Unmap；三是 CIDR 输入走 ParsePrefix，网络展示走 Masked，成员关系走 Contains；四是日志和 UI 用 String，二进制接口才读取 As4/As16。

这套顺序的好处是每一层只有一个职责：解析层处理语法，分类层处理地址族，网段层处理前缀，输出层处理表现形式。以后如果新增 IPv4 白名单或日志归一化，只需要在分类层明确策略，不必到处修改字符串判断。

常见误区与速查表

如果只记住一句话：先解析，再识别映射，再决定归一化；网段输入和地址输出各自使用专门的方法。这样既能处理常见 IPv4，也能对 IPv6 和 IPv4 映射 IPv6 保持明确语义。

官方资料：https://pkg.go.dev/net/netip；https://go.dev/src/net/netip/netip.go。

相关问题

ParseAddr 能解析主机名吗？

不能。它解析的是数值 IP 文本；主机名解析属于 DNS 或网络解析流程，不在本文范围内。

为什么 ParsePrefix 后还要调用 Masked？

因为前缀对象可以保留输入地址中未被前缀覆盖的位。只有需要网络起点时，才显式调用 Masked。

带 zone 的 IPv6 能放进 Prefix 吗？

不能。IPv6 zone 不允许出现在前缀文本中，解析时应把这个错误作为输入不符合 CIDR 契约处理。