Go netip.Addr.As16 怎样转换成固定长度地址字节

Go 的 netip.Addr.As16() 会返回一个固定长度的 [16]byte。 对 IPv6，它保留 16 字节地址；对 IPv4，它返回 IPv4-mapped IPv6 形式；对带 zone 的 IPv6，zone 不会进入这 16 个字节。需要原始 IPv4 四字节表示时，应使用 As4()，而不是截取 As16() 的尾部。

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

这使它适合做固定宽度的键、二进制字段或内存中的统一表示，但前提是调用方知道“字节相同”与“文本写法相同”不是一回事。下面按输入状态、转换结果和回转边界拆开说明。

先把输入状态分清

netip.Addr 是不可变、可比较的值类型。写入固定宽度存储前，先区分普通 IPv4、普通 IPv6、IPv4-mapped IPv6 和零值 Addr{}。其中 IPv4-mapped IPv6 是真正的 IPv6 地址形态，不能只看到尾部是 IPv4 就把它当作 Is4() 为真。

用 As16 获得固定宽度字节

返回值是数组而不是切片，因此长度在类型层面就是 16。数组可以直接作为 map 的键，也可以通过切片表达式交给需要 []byte 的编码函数。不要把它理解成“把字符串转成 16 个字符”，它保存的是地址的二进制表示。

package main

import (
    "encoding/hex"
    "fmt"
    "net/netip"
)

func main() {
    inputs := []string{"192.0.2.1", "2001:db8::1"}
    for _, text := range inputs {
        ip, err := netip.ParseAddr(text)
        // 解析失败时跳过输入，避免把无效地址继续写入二进制字段。
        if err != nil {
            fmt.Printf("解析失败: %s: %v\\n", text, err)
            continue
        }
        raw := ip.As16()
        // 数组切片只用于编码展示，原始返回值仍然是 [16]byte。
        fmt.Printf("%s valid=%t len=%d hex=%s\\n", ip, ip.IsValid(), len(raw), hex.EncodeToString(raw[:]))
    }
}

这个例子中的 len(raw) 恒为 16。IPv4 的十六进制结果会包含 IPv4-mapped IPv6 的前缀；IPv6 则直接对应其 128 位地址。若字段协议明确规定只接受四字节 IPv4，继续使用 As16() 会把字段语义写错。

IPv4 映射形式和 zone 要单独处理

IPv4 调用 As16() 后得到的是映射到 IPv6 地址空间的形式。这个设计保证不同地址族都能进入同一宽度的容器，但不等于“IPv4 变成了普通 IPv6”。如果业务需要判断来源地址族，先看 Is4()、Is4In6()，或者对明确的映射地址调用 Unmap()。

带区域标识的 IPv6，例如 fe80::1%eth0，区域标识用于接口范围，不属于 128 位地址本体。As16() 返回的字节不携带 eth0；如果后续还要恢复链路本地地址的接口语义，应另行保存 Zone()。

package main

import (
    "fmt"
    "net/netip"
)

func show(text string) {
    ip, err := netip.ParseAddr(text)
    // 只有解析成功后才访问地址族判断和固定字节表示。
    if err != nil {
        fmt.Printf("%s: %v\\n", text, err)
        return
    }
    raw := ip.As16()
    // Is4In6 与 Is4 不同，用于识别 IPv4-mapped IPv6 语义。
    fmt.Printf("ip=%s is4=%t is4in6=%t zone=%q first=%02x last=%02x\\n",
        ip, ip.Is4(), ip.Is4In6(), ip.Zone(), raw[0], raw[15])

    if ip.Is4In6() {
        // Unmap 只去掉映射外壳，不负责恢复任何 zone 信息。
        fmt.Printf("unmapped=%s\\n", ip.Unmap())
    }
}

func main() {
    show("192.0.2.1")
    show("::ffff:192.0.2.1")
    show("fe80::1%eth0")
}

这里的重点不是打印某个运行日志，而是把判断顺序固定下来：先解析，确认地址族，再决定是否需要 Unmap()；如果协议还需要接口范围，就把 Zone() 当成单独字段保存。

需要四字节 IPv4 时改用 As4

As4() 只适用于 IPv4 或 IPv4-in-IPv6 地址，并返回 [4]byte。对普通 IPv6 调用它会 panic，因此解析不可信输入时不能无条件调用。与其对 As16() 的后四个字节做切片，不如让 API 直接表达“我需要 IPv4 四字节表示”。

package main

import (
    "fmt"
    "net/netip"
)

func ipv4Bytes(text string) ([4]byte, bool) {
    ip, err := netip.ParseAddr(text)
    // 返回 false 代表输入不是可接受的 IPv4，而不是让调用方捕获 panic。
    if err != nil || !ip.Is4() {
        return [4]byte{}, false
    }
    return ip.As4(), true
}

func main() {
    raw, ok := ipv4Bytes("192.0.2.1")
    // ok 为真时才把四字节数组交给 IPv4 专用协议字段。
    fmt.Printf("ok=%t bytes=%v\\n", ok, raw)
}

如果输入可能是 IPv4-mapped IPv6，先按业务决定是否接受这种语义。接受时可以先调用 Unmap() 再判断 Is4()；不接受时则应把它作为 IPv6 形式处理，而不是静默改变地址族。

零值与反向恢复的边界

零值 Addr{} 的 As16() 会得到全零数组，但 :: 与 0.0.0.0 也是有效地址，不能用“16 个字节全零”反推输入无效。判断有效性应保留原来的 Addr，使用 IsValid()，或在序列化协议中显式记录缺失状态。

如果你从固定字节恢复地址，可使用 netip.AddrFrom16()。它恢复的是 IPv6 地址；对 IPv4-mapped IPv6 也会保留 IPv6 映射形态，需要时再调用 Unmap()。注意恢复过程同样无法找回 IPv6 zone，因为 zone 从一开始就不在 As16() 的 16 个字节里。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    original := netip.MustParseAddr("192.0.2.1")
    raw := original.As16()
    restored := netip.AddrFrom16(raw)
    // 恢复后先观察映射语义，再按业务决定是否 Unmap。
    fmt.Printf("original=%s restored=%s unmapped=%s\\n", original, restored, restored.Unmap())

    var zero netip.Addr
    // 全零字节可能同时对应有效的未指定地址，不能替代 IsValid 判断。
    fmt.Printf("zero-valid=%t zero-bytes=%v\\n", zero.IsValid(), zero.As16())
}

As16 返回的是切片还是数组？

是 [16]byte 数组。需要传给接收切片的函数时使用 raw[:]，但不要因此把返回类型理解成可变的共享底层缓冲区。

IPv4 的 As16 结果能直接当普通 IPv6 吗？

它是 IPv4-mapped IPv6 表示，适合统一宽度存储；如果业务要保留“这是 IPv4”的语义，应同时保存地址族或在使用前调用 Unmap()。

As16 能保留 IPv6 的 zone 吗？

不能。zone 不属于 16 字节地址本体，需要通过 Zone() 单独保存。

实际选择可以压缩成一句话：统一存储、比较或做固定字段时用 As16()；IPv4 专用四字节协议用 As4()；处理映射语义用 Unmap()；判断无效输入始终保留并检查 Addr.IsValid()。

参考：https://pkg.go.dev/net/netip#Addr.As16、https://pkg.go.dev/net/netip#Addr.As4、https://pkg.go.dev/net/netip#Addr.Unmap