Go netip.Prefix.String 怎样输出标准 CIDR 文本

处理 IP 网段时，netip.Prefix.String() 的职责很明确：把 Prefix 按 / 形式输出成 CIDR 文本。它不会替你判断地址是否属于网段，也不会自动把 Prefix 中保留的主机位归零。要得到可直接写入日志或配置的规范网段，先确认有效性，必要时调用 Masked()，最后再调用 String()。

Prefix.String 返回的 CIDR 结构

最常见的写法是先解析一个已经带前缀长度的字符串，再调用 String()。IPv4 会得到点分十进制地址，IPv6 会得到压缩后的 IPv6 文本，斜线后的数字来自 Bits()。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    // 固定示例适合测试；生产输入应改用 ParsePrefix 处理错误。
    prefix, err := netip.ParsePrefix("192.0.2.0/24")
    if err != nil {
        // 输入不是合法 CIDR 时不要继续写入配置或日志。
        panic(err)
    }

    // String 返回可读的 ip/bits 形式，例如 192.0.2.0/24。
    fmt.Println(prefix.String())
}

这里的结果是文本，不是可继续做网段运算的替代对象。若程序要判断包含关系，仍应保留 Prefix，并使用 Contains；若只是做键、日志字段或配置展示，String() 足够直接。

主机位未归零时，先决定是否规范化

容易误判的场景来自 PrefixFrom。官方文档明确说明，它不会像 Addr.Prefix 那样清除主机位。因此下面的 Prefix 可能保留 192.0.2.129 这个地址，再附带 /24；这不是 String 拼错，而是对象本身携带了非规范地址。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    addr := netip.MustParseAddr("192.0.2.129")
    raw := netip.PrefixFrom(addr, 24)

    // PrefixFrom 保留主机位，适合需要保留原始地址的场景。
    fmt.Println(raw.String())

    // Masked 只保留高 bits 位，得到可作为网段键的规范形式。
    fmt.Println(raw.Masked().String())
}

如果文章、缓存键或配置文件表达的是“网络块”，建议输出 raw.Masked().String()；如果表达的是“带前缀长度的原始地址”，才保留 raw.String()。不要只靠字符串后处理截断地址，IPv6 的压缩规则会让这种做法变得脆弱。

零值和非法 Prefix 要在输出前拦截

Prefix 的零值不是一个可用网段，IsValid() 会返回 false。对于来自请求、文件或环境变量的输入，优先使用 ParsePrefix；对于代码中硬编码且确定正确的值，才使用 MustParsePrefix。Bits() 返回 -1 时也应视作无效状态。

func formatPrefix(p netip.Prefix) (string, bool) {
    // 先判断对象状态，避免把零值写成看似合法的配置。
    if !p.IsValid() || p.Bits() 

这一步还能把错误处理集中在一个边界函数里：调用方只接收有效 CIDR，解析失败、零值和超出地址位数的前缀长度都不会混入后续逻辑。

String、Masked 与文本序列化的选择

String() 适合日志、调试输出和页面展示；MarshalText() 实现了文本封送接口，零值 Prefix 的编码是空文本，更适合由编码器统一处理的配置字段；Go 1.24 及之后还可以用 AppendText 追加到已有缓冲区。它们都不替代 Masked()，规范化仍然是单独的对象处理动作。

常见问题

Prefix.String 会自动把主机位归零吗？

不会。String 只按对象当前的地址和 Bits 生成 CIDR 文本；需要规范网段时显式调用 Masked。

零值 Prefix 能直接写入配置吗？

不建议。先检查 IsValid；若业务允许空值，用 MarshalText 的空文本语义并在配置层明确区分空值与合法的 0.0.0.0/0。

为什么不用字符串截取来生成网段键？

因为 IPv4 和 IPv6 的文本规则不同，截取无法可靠处理压缩、映射地址和前缀长度。对象层调用 Masked，再调用 String 更稳定。

实际使用时可以记住一个顺序：先判断 Prefix 是否有效，再根据业务决定是否 Masked，最后选择 String、MarshalText 或 AppendText。这样输出的 CIDR 文本既可读，也不会掩盖对象状态。