Go netip.Addr.AppendBinary 将 IP 追加为二进制地址的处理方法

在协议字段、二进制日志或缓存键中写入 IP 时，netip.Addr.AppendBinary 适合“追加到已有 []byte”这个具体任务。它实现的是二进制追加接口：IPv4 追加 4 个地址字节，IPv6 追加 16 个地址字节；调用方必须接住返回切片，并检查错误。它不是把 IP 写成可读的 192.0.2.1 文本。

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

先把三种输出方式分开

AppendBinary 面向机器读取的地址字节；AppendText 和 AppendTo 面向文本。一个常见误区是看到“追加”就把结果当成字符串缓冲区，之后又按 UTF-8 或冒号分隔去解析，这会让协议两端的字段契约失配。

用返回切片承接追加结果

目标切片可以带有协议头或版本号。下面的写法保留前缀，再把 IPv4 地址追加到末尾；注释解释了返回值和错误的关键边界。

package main

import (
    "fmt"
    "net/netip"
)

func encodeAddr(prefix []byte, text string) ([]byte, error) {
    // 解析阶段拒绝非数字地址，避免把解析问题混进二进制编码阶段。
    ip, err := netip.ParseAddr(text)
    if err != nil {
        return nil, fmt.Errorf("parse address: %w", err)
    }
    // AppendBinary 可能复用 prefix，也可能返回新底层数组，必须接住返回值。
    out, err := ip.AppendBinary(prefix)
    if err != nil {
        return nil, fmt.Errorf("append binary address: %w", err)
    }
    return out, nil
}

func main() {
    // 这里的 0x01 是示意性的协议版本字段，不是 IP 数据的一部分。
    out, err := encodeAddr([]byte{0x01}, "192.0.2.1")
    if err != nil {
        panic(err)
    }
    fmt.Printf("% x\\n", out) // 结果示意：01 c0 00 02 01
}

如果目标切片容量足够，函数可能直接在原数组后写入；容量不足时会扩容。对调用方而言，这两种情况没有区别：后续字段都应继续使用 out，而不是继续使用旧的 prefix 变量。

IPv4、IPv6 和零值要分别验收

地址族决定追加长度，但不应该由业务代码手工猜测。Addr.BitLen() 可以帮助记录字段长度；IsValid() 则用于拦截零值地址。零值与明确的 0.0.0.0 不是一回事，后者是有效的 IPv4 unspecified 地址。

func appendChecked(dst []byte, ip netip.Addr) ([]byte, error) {
    // 零值 Addr 表示没有地址，不能默默编码成全零 IP。
    if !ip.IsValid() {
        return nil, fmt.Errorf("invalid zero address")
    }
    before := len(dst)
    out, err := ip.AppendBinary(dst)
    if err != nil {
        return nil, err
    }
    // 只根据返回切片计算增量，避免把 cap 当成已写入长度。
    want := 4
    if ip.Is6() {
        want = 16
    }
    if len(out)-before != want {
        return nil, fmt.Errorf("unexpected encoded length: got %d want %d", len(out)-before, want)
    }
    return out, nil
}

这个检查适合协议编码层。若上游已经用 ParseAddr 得到有效地址，错误通常来自未来新增的类型或接口组合；保留错误分支仍然有价值，因为 AppendBinary 的签名明确要求调用方处理错误。

把协议字段长度写进检查清单

如果 IP 后面还要追加端口、校验码或消息体，建议把每个字段的追加结果串起来，并让一次提交动作只接收最终切片。不要凭经验写死“每个地址都是16字节”，因为 IPv4 的二进制表示更短；也不要把 As16 的 16 字节视图与 AppendBinary 混用，除非协议明确要求 IPv4 映射的16字节格式。

相关问题

AppendBinary 会修改传入的切片吗？

它会把结果追加到传入切片的逻辑末尾；是否复用原底层数组取决于容量。因此应使用返回切片，不能依赖旧切片的容量变化。

为什么不直接用 Addr.AsSlice？

AsSlice 返回地址的 4 或16字节表示，适合读取或复制；AppendBinary 更适合把地址接到已有协议缓冲区，并统一处理追加返回值和错误。

IPv4 是否应该强制补成16字节？

只有协议字段明确规定16字节时才这样做。AppendBinary 按地址族追加；若协议要固定宽度，应在编码层明确约定并单独处理。