Go netip.ParsePrefix 规范化 CIDR 主机位的实现方法

使用 netip.ParsePrefix 解析 CIDR 后，不能默认得到的地址已经是网络地址。官方文档明确说明：被掩码覆盖的地址位不会自动清零。需要稳定保存或比较网段时，先调用 Prefix.Masked()；需要判断某个 IP 是否属于网段时，再使用规范化后的 Prefix 调用 Contains。

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

ParsePrefix 解析的是前缀长度，不是自动改写地址

下面这个输入在语法上是合法 CIDR，但 192.0.2.19 并不是 /24 对应的网络地址。ParsePrefix 会保留这段地址信息，调用方应根据业务决定是否规范化。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    // 解析结果保留输入地址，/24 只表示前 24 位属于网络前缀。
    p, err := netip.ParsePrefix("192.0.2.19/24")
    if err != nil {
        // 配置输入错误应立即返回，不能拿零值 Prefix 继续判断。
        panic(err)
    }

    fmt.Println(p)        // 192.0.2.19/24
    fmt.Println(p.Addr()) // 192.0.2.19
    fmt.Println(p.Bits()) // 24
}

用 Masked 生成可比较、可保存的网段值

如果配置中心、缓存键或数据库字段需要保存“网段”，建议在边界处统一调用 Masked。它按照 Bits() 保留网络位，把主机位归零，并返回新的 Prefix；原始 Prefix 仍可单独保留用于记录用户输入。

func normalizeCIDR(raw string) (netip.Prefix, error) {
    // 先校验 CIDR，再把地址规范化为网络地址。
    p, err := netip.ParsePrefix(raw)
    if err != nil {
        return netip.Prefix{}, fmt.Errorf("解析 CIDR %q: %w", raw, err)
    }
    // Masked 不修改 p，返回适合比较和持久化的规范形式。
    return p.Masked(), nil
}

func main() {
    p, err := normalizeCIDR("192.0.2.19/24")
    if err != nil {
        // 调用方可以把错误映射为配置校验失败，而不是继续启动服务。
        panic(err)
    }
    fmt.Println(p) // 192.0.2.0/24
}

注意，Masked 适合“网络段”语义，不适合替代用户输入审计。若需要回显原字符串，应另存原始文本；若需要做唯一键、集合去重或稳定日志，则使用规范化结果。

按任务区分 Addr、Bits、Contains 和 String

Contains 本身表达的是“这个 Prefix 是否包含某个地址”，不要把字符串前缀匹配当成网络判断。IPv4 与 IPv6 地址族也不会因为文本相似而互相匹配；如果数据来自用户配置，先处理解析错误，再明确是否允许两种地址族。

常见问题

ParsePrefix 为什么不直接返回 192.0.2.0/24？

因为它需要保留输入地址与前缀长度的解析结果，是否清零主机位属于调用方的语义选择。网段配置场景调用 Masked 即可。

Masked 会修改原来的 Prefix 吗？

不会。Prefix 是值类型，Masked 返回规范化后的新值；如果同时需要原始输入和规范化网段，可以分别保存。

只比较 String 是否足够？

只有在两边都先规范化且输入已确认有效时才适合作为展示或键值。业务归属判断应使用 Contains，不要依赖字符串拼接。