Go netip.Prefix.AppendTo 怎么构造稳定网段文本：IPv4 IPv6 与零值边界

网段文本要写进日志、协议字段或复用的字节缓冲区时，直接调用 Prefix.String() 往往会先产生一个字符串。Go 的 netip.Prefix.AppendTo 可以把规范化后的前缀直接追加到已有 []byte，但它不会替你判断零值是否有效，也不会修正错误的前缀长度。把输入、校验和追加动作分开，IPv4、IPv6 两条路径就能稳定下来。

先用 Prefix.IsValid() 拦住零值和非法前缀，再让 AppendTo 负责写出 CIDR 文本；需要复用缓冲区时，优先保留返回后的切片。

先把地址和前缀长度放进同一条数据路径

示例函数接收一个地址和位数，先构造 netip.Prefix，再把文本追加到调用方提供的缓冲区。这里的关键不是“把 IP 转成字符串”，而是让输入、组合对象、输出缓冲区三者的关系可复查。

package main

import (
    "fmt"
    "net/netip"
)

func appendCIDR(dst []byte, addr netip.Addr, bits int) ([]byte, error) {
    prefix, err := netip.PrefixFrom(addr, bits)
    if err != nil {
        return dst, err
    }
    if !prefix.IsValid() {
        return dst, fmt.Errorf("invalid prefix")
    }
    return prefix.AppendTo(dst), nil
}

在这条链路里，PrefixFrom 先把地址和长度组合成前缀，IsValid 再确认对象可用，最后由 AppendTo 修改并返回 dst。返回值必须接住，因为追加可能扩容并返回新的底层切片。

IPv4 和 IPv6 的位数校验不能混在一起猜

netip.PrefixFrom 的第二个参数是前缀长度。IPv4 合法范围是 0 到 32，IPv6 合法范围是 0 到 128。不要用字符串里是否包含冒号来判断类型，直接使用 addr.Is4() 和 addr.Is6() 更清楚。

如果输入来自配置文件，建议先用 netip.ParseAddr 得到地址，再按地址类型选择位数上限。这样错误会在靠近数据源的位置暴露，不会等到写日志或拼协议字段时才发现。

复用缓冲区时，AppendTo 的返回值就是新状态

下面的调用把固定前缀先写入缓冲区，再追加网段。为了让示例可验收，分别打印长度和内容；实际日志代码可以把返回的切片交给下一步编码。

func main() {
    addr4 := netip.MustParseAddr("192.0.2.15")
    out, err := appendCIDR(make([]byte, 0, 32), addr4, 24)
    if err != nil {
        panic(err)
    }
    fmt.Printf("len=%d value=%s\n", len(out), out)

    addr6 := netip.MustParseAddr("2001:db8::15")
    out, err = appendCIDR(out[:0], addr6, 64)
    if err != nil {
        panic(err)
    }
    fmt.Printf("len=%d value=%s\n", len(out), out)
}

第一行应得到 192.0.2.0/24，因为前缀文本会按网段规范化地址；第二行应得到 2001:db8::/64。out[:0] 只复用容量，不复用上一条内容的长度。

三个容易漏掉的边界

零值前缀不能当成默认网段

netip.Prefix{} 不是一个可直接发布的业务网段。先调用 IsValid，无效时返回错误，让调用方决定记录、丢弃还是使用明确的默认配置。

前缀长度不是地址字节长度

IPv4 的 /24 表示 24 个网络位，不是 24 字节；IPv6 的 /64 也不是 64 字节。把配置字段从“字节数”误传给 PrefixFrom，通常会很快得到错误，但在自定义转换代码里可能被掩盖。

不要忽略追加后的切片

当 dst 容量不足时，AppendTo 可能返回指向新数组的切片。写成 prefix.AppendTo(dst) 而不接收结果，短输入下似乎没问题，扩容时就会丢掉输出。

如何做一组最小回归检查

至少覆盖一个 IPv4、一个 IPv6、零值地址和越界位数。检查点不是只看函数有没有报错，还要比较输出是否已按前缀归一化，并确认复用缓冲区后长度从零重新计算。

func TestAppendCIDR(t *testing.T) {
    cases := []struct {
        name string
        addr string
        bits int
        want string
    }{
        {"v4", "192.0.2.15", 24, "192.0.2.0/24"},
        {"v6", "2001:db8::15", 64, "2001:db8::/64"},
    }
    for _, tc := range cases {
        addr := netip.MustParseAddr(tc.addr)
        got, err := appendCIDR(nil, addr, tc.bits)
        if err != nil || string(got) != tc.want {
            t.Fatalf("%s: got %q, err %v", tc.name, got, err)
        }
    }
}

相关问题

AppendTo 会改变原来的 Prefix 吗？

不会。它把文本追加到目标字节切片，Prefix 本身仍是值类型对象；需要继续使用输出时保存返回切片即可。

为什么输出地址和输入地址不一样？

因为前缀表示的是网段，主机位会被归一化为网络地址。例如 192.0.2.15/24 输出为 192.0.2.0/24。

什么时候直接用 String 更合适？

只有在确实需要一个独立字符串、且不在热路径上复用缓冲区时，String 更直观；协议编码或批量日志场景更适合保留 AppendTo 的返回切片。

把检查放在输入边界，输出就容易验收

这套写法的重点是把职责拆开：解析得到 Addr，组合得到 Prefix，用 IsValid 做门禁，再由 AppendTo 写入缓冲区。这样既能覆盖 IPv4/IPv6 的不同位数，也能避免零值和切片扩容把问题藏到下游。