Go net/netip 怎样区分 IP 地址和前缀

我在做一层网络规则配置时遇到过一个很典型的输入混杂问题：字段里有时是 192.0.2.10，有时却是 192.0.2.0/24。前者表示一个 IP 地址，后者表示一个网段；如果都当成字符串保存，后面的白名单判断和规范化就会越来越绕。

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

在 Go 的 net/netip 中，单个 IP 地址使用 netip.Addr，带 CIDR 位数的网段使用 netip.Prefix。先按输入语义选择类型，再分别调用 ParseAddr 或 ParsePrefix，不要把两者混为一个字符串字段。

从真实输入症状开始分流

先看输入是否包含 CIDR 的斜杠，是一个简单且符合字段语义的分流点。没有斜杠时，调用方要的是一个端点；有斜杠时，调用方要的是一段地址范围。这个判断不是为了“猜测字符串”，而是把配置格式明确映射到领域类型。

package main

import (
    "fmt"
    "net/netip"
    "strings"
)

func parseNetworkValue(raw string) (any, error) {
    raw = strings.TrimSpace(raw) // 先去除配置文件中常见的首尾空格。
    if strings.Contains(raw, "/") {
        prefix, err := netip.ParsePrefix(raw) // 带位数的是 CIDR 前缀，不是单个地址。
        if err != nil {
            return nil, fmt.Errorf("parse prefix %q: %w", raw, err) // 保留输入和底层原因。
        }
        return prefix, nil
    }

    addr, err := netip.ParseAddr(raw) // 不带斜杠的输入按单个 IPv4 或 IPv6 地址解析。
    if err != nil {
        return nil, fmt.Errorf("parse address %q: %w", raw, err) // 让调用方知道是哪一个字段失败。
    }
    return addr, nil
}

示例中的返回值用了 any，只是为了展示分流过程。生产代码通常会让配置结构显式区分 Addr 和 Prefix，或者定义一个带类型标记的值对象，避免调用方到处做类型断言。

分别解析 Addr 和 Prefix

Addr 是一个不可变、可比较的 IP 地址值，适合做 map 的键或作为白名单中的单个成员。Prefix 表示 CIDR 前缀，除了地址本身还带有有效位数，例如 /24 表示前 24 位参与网络匹配。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    addr, err := netip.ParseAddr("192.0.2.10") // 解析一个具体端点。
    if err != nil {
        panic(err) // 示例输入是固定值，失败时直接终止示例。
    }

    prefix, err := netip.ParsePrefix("192.0.2.0/24") // 解析一个 CIDR 地址范围。
    if err != nil {
        panic(err) // 生产代码应把错误返回给配置加载流程。
    }

    fmt.Println(addr, addr.BitLen())       // Addr 可报告 IPv4 或 IPv6 的总位数。
    fmt.Println(prefix, prefix.Bits())     // Prefix 同时保存地址和前缀长度。
    fmt.Println(prefix.IsValid())          // 进入业务逻辑前可检查零值或非法位数。
}

不要仅凭 String() 的结果判断类型：Addr.String() 和 Prefix.String() 都能生成文本。类型本身才表达“单个地址”还是“地址范围”的约束。

读取 Prefix 的组成并规范化

从 Prefix 取出 Addr() 和 Bits()，可以把网段拆成“地址部分”和“匹配长度”。需要注意，解析得到的前缀地址位不一定已经是网络地址；如果要展示或存储规范的网段，应调用 Masked()。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    prefix, err := netip.ParsePrefix("192.0.2.17/24") // 故意使用带主机位的地址观察差异。
    if err != nil {
        panic(err)
    }

    canonical := prefix.Masked() // 只保留前 Bits 位，把主机位归零。
    fmt.Println("原始:", prefix)
    fmt.Println("地址:", prefix.Addr())
    fmt.Println("位数:", prefix.Bits())
    fmt.Println("规范:", canonical)
}

这里的重点是：ParsePrefix 能接受带主机位的前缀文本，但不会自动把地址位清零；Masked 才负责生成规范形式。对配置去重、日志展示或作为缓存键时，这个区别很重要。

判断地址是否属于网段

当业务问题变成“这个地址是否在白名单网段内”，直接用 Prefix.Contains，不要自己截取字符串或手写位运算。它会区分 IPv4、IPv6 和 IPv4-mapped IPv6 等地址族，零值地址也不会被误判为匹配。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    allowed := netip.MustParsePrefix("192.0.2.0/24") // 固定在代码中的规则可使用 MustParsePrefix。
    candidates := []string{"192.0.2.10", "192.0.3.10", "2001:db8::1"}

    for _, raw := range candidates {
        addr, err := netip.ParseAddr(raw) // 每个候选值仍然先按 Addr 解析。
        if err != nil {
            fmt.Printf("%s: 输入错误: %v\n", raw, err) // 线上配置不能把坏输入当成不匹配。
            continue
        }
        fmt.Printf("%s: %t\n", raw, allowed.Contains(addr)) // Contains 负责范围和地址族判断。
    }
}

MustParsePrefix 适合测试或硬编码常量；如果前缀来自用户、环境变量或配置文件，仍应使用 ParsePrefix 并向上返回错误。

避免 Addr.Prefix 和 PrefixFrom 带来的误判

这两个 API 都能从地址和位数得到前缀，但语义不同。Addr.Prefix(bits) 会把主机位屏蔽掉，得到规范的前缀；PrefixFrom(addr, bits) 只是把给定地址和位数装入一个 Prefix，不会自动清理主机位。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    addr := netip.MustParseAddr("192.0.2.17") // 这个地址的最后一段包含主机位。

    masked, err := addr.Prefix(24) // 该方法会按 24 位生成规范网络前缀。
    if err != nil {
        panic(err)
    }
    raw := netip.PrefixFrom(addr, 24) // 该方法保留传入地址中的主机位。

    fmt.Println(masked)        // 192.0.2.0/24
    fmt.Println(raw)           // 192.0.2.17/24
    fmt.Println(raw.Masked())  // 再显式规范化后才是 192.0.2.0/24
}

如果你的目标是构造白名单、路由前缀或缓存键，优先使用 Addr.Prefix，或者对 PrefixFrom 的结果立即调用 Masked。只有在确实需要保留输入地址位、并且后续逻辑知道这个差异时，才直接保存未规范化的 PrefixFrom 结果。

把选择收束为一张清单

我最后采用的规则是：字段代表一个端点，就保存 Addr；字段代表一段范围，就保存 Prefix；需要持久化或比较前缀时，先明确是否要调用 Masked。这样类型选择、错误处理和范围判断都在同一条语义链上，后续不用靠字符串格式补救。

相关问题

netip.Addr 和旧的 net.IP 怎么选？新代码如果需要不可变、可比较的地址值，优先考虑 netip.Addr；与旧 API 对接时再按边界转换。

ParsePrefix 会自动把主机位清零吗？不会。需要规范网络地址时调用 Masked。

为什么 IPv6 前缀不能带 zone？zone 用于限定链路本地地址的接口，而 Prefix 表示网络范围；解析 CIDR 时应把 zone 排除在格式之外。

配置字段只有一个字符串时该怎么做？可以按是否包含斜杠分流，但建议在解析后尽快转换为带明确类型的结构，避免业务层重复猜测。