Go netip.Addr.BitLen 怎样区分 IPv4 和 IPv6 的位宽

在 Go 的地址处理代码里，netip.Addr.BitLen() 很适合做一个轻量的分支信号：IPv4 返回 32，IPv6 返回 128，零值 Addr{} 返回 0。它返回的是位数，不是字节数。需要特别注意的是，IPv4-mapped IPv6 会被当作 IPv6，结果仍然是 128。

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

因此，业务代码可以先解析地址，再根据 BitLen 选择前缀长度、位图宽度或序列化分支；但不要把 0 当成一种合法的网络地址。

BitLen 的返回契约

BitLen 的规则非常集中，先记住下面三种状态：

这里最容易混淆的是“零值”和“未指定地址”。netip.Addr{} 表示没有有效地址；0.0.0.0 和 :: 是有效的未指定地址，它们仍然分别具有 32 位和 128 位宽度。若代码需要识别无效输入，应优先检查 IsValid()，不要只把 BitLen()==0 当作网络业务状态。

解析后用 BitLen 做清晰分支

实际入口通常是字符串。推荐先处理解析错误，再处理零值和位宽。这样既能区分格式错误，也能避免把无效地址带入后续计算。

package main

import (
    "fmt"
    "net/netip"
)

func describe(raw string) error {
    // ParseAddr 负责把文本解析成值类型；解析失败时不要继续读取位宽。
    ip, err := netip.ParseAddr(raw)
    if err != nil {
        return fmt.Errorf("解析 IP 失败: %w", err)
    }

    // BitLen 返回 32、128 或 0，0 只代表 Addr 的零值。
    switch ip.BitLen() {
    case 32:
        fmt.Println("IPv4，按 32 位处理")
    case 128:
        fmt.Println("IPv6，按 128 位处理")
    case 0:
        // 这个分支主要保护零值；ParseAddr 成功时通常不会得到它。
        fmt.Println("无效的零值地址")
    default:
        // 标准库当前只定义上述结果，保留默认分支便于未来审查。
        return fmt.Errorf("未知地址位宽: %d", ip.BitLen())
    }
    return nil
}

如果入口不是字符串，而是某个结构体里的 netip.Addr 字段，可以同样先调用 IsValid()，再读取 BitLen()。对于协议分支，使用明确的 case 32 和 case 128 比判断“是否为 IPv6”更直接，因为映射地址的归类容易让人误判。

IPv4-mapped IPv6 为什么是 128 位

地址 ::ffff:192.0.2.1 看起来包含一个 IPv4 地址，但它在 netip.Addr 中仍然是 IPv6 表示。官方文档明确说明：IPv4-mapped IPv6 被视为 IPv6，因此 BitLen() 返回 128；同时 Is4() 返回 false，Is4In6() 返回 true。

func inspectMapped(raw string) error {
    // 使用带映射形式的地址，观察 BitLen 与 Is4 的组合结果。
    ip, err := netip.ParseAddr(raw)
    if err != nil {
        return fmt.Errorf("解析映射地址失败: %w", err)
    }

    // Is4In6 用来识别映射关系；BitLen 仍按 IPv6 的 128 位解释。
    fmt.Printf("bitLen=%d is4=%v is4In6=%v\n", ip.BitLen(), ip.Is4(), ip.Is4In6())

    // 只有业务明确需要普通 IPv4 语义时，才显式取消映射。
    if ip.Is4In6() {
        ip = ip.Unmap()
        fmt.Printf("unmapped=%s bitLen=%d\n", ip, ip.BitLen())
    }
    return nil
}

这段逻辑体现了一个重要取舍：BitLen 描述当前 Addr 的地址表示，而不是猜测它“原本想表达什么”。如果协议层要求统一为 IPv4，先用 Is4In6 判断，再调用 Unmap()；不要因为字符串中出现了点分十进制片段，就直接把位宽改成 32。

把位宽用于 Prefix 和序列化

BitLen 的一个实用价值，是给前缀长度提供边界。Addr.Prefix(bits) 要求 bits 不小于 0 且不超过当前地址的位宽，因此可以用它避免 IPv4 误传 64、IPv6 误传 160 之类的错误参数。

func prefixFor(ip netip.Addr, bits int) (netip.Prefix, error) {
    // 先拒绝零值，避免把无效 Addr 当作默认网段继续传播。
    if !ip.IsValid() {
        return netip.Prefix{}, fmt.Errorf("地址无效")
    }

    // 用当前地址位宽约束 bits，Prefix 会继续完成实际的范围检查。
    if bits < 0 || bits > ip.BitLen() {
        return netip.Prefix{}, fmt.Errorf("前缀长度 %d 超过地址位宽 %d", bits, ip.BitLen())
    }
    return ip.Prefix(bits)
}

序列化时也要先确定目标格式。AsSlice() 会按地址类型返回 4 字节或 16 字节表示；如果业务必须统一成 16 字节，可以使用 As16()，但要清楚 IPv4 会被表示成 IPv4-mapped IPv6。位宽和字节长度相关，却不是同一个概念：32 位对应 4 字节，128 位对应 16 字节。

常见误区与快速判断

• 把 BitLen() 当成字节数：需要分配字节数组时，应使用 BitLen()/8 或直接依据 AsSlice() 的结果。
• 把 Addr{} 当成 0.0.0.0：零值无效，未指定地址有效，两者都不能只靠字符串直觉判断。
• 把 IPv4-mapped IPv6 当成普通 IPv4：先检查 Is4In6()，再决定是否 Unmap()。
• 用位宽判断安全属性：BitLen 只描述地址表示，不等于公网、私网、回环或可达性判断。

总结

用 Addr.BitLen() 区分 IPv4 和 IPv6 时，核心规则只有三条：普通 IPv4 返回 32，普通 IPv6 返回 128，零值 Addr{} 返回 0。IPv4-mapped IPv6 是最需要单独记忆的边界，它按 IPv6 处理并返回 128。工程代码中建议先检查解析错误和 IsValid()，再用位宽约束 Prefix 或选择序列化策略；如果需要普通 IPv4 语义，再显式调用 Unmap()。

相关问题

BitLen 返回 0 就是 0.0.0.0 吗？

不是。0 表示零值 Addr{}，而 0.0.0.0 是有效的 IPv4 地址，BitLen 返回 32。

IPv4-mapped IPv6 能直接调用 As4 吗？

可以。As4 支持 IPv4-in-IPv6 表示；但如果业务要把它作为普通 IPv4 保存或比较，仍建议先明确是否需要 Unmap()。

判断 IPv4 应该用 BitLen 还是 Is4？

判断当前地址是否是普通 IPv4 时用 Is4() 更直观；需要同时约束 Prefix 长度或处理位图宽度时，再使用 BitLen()。