Go netip.Prefix Contains 为什么要先规范化网络位

调用 netip.Prefix.Contains 并不要求先 Masked。它按前缀长度比较网络位，不会把保留的主机位当作网络匹配条件。建议先规范化，主要是为了统一网段的文本、相等比较和 map 键。如果 Contains 的结果不符合预期，单补一个 Masked 未必能解决，应该继续检查地址族、前缀长度和输入有效性。

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

最小写法：同一个前缀，分别观察表示和匹配

下面的完整示例使用文档示例地址段，展示两个容易混淆的问题：地址是否属于网络，以及两个 Prefix 值是否相等。代码不依赖网络请求。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    raw, err := netip.ParsePrefix("192.0.2.157/24")
    if err != nil {
        // 外部输入需要处理解析错误，不能悄悄使用零值。
        fmt.Println("prefix:", err)
        return
    }
    candidate, err := netip.ParseAddr("192.0.2.23")
    if err != nil {
        fmt.Println("address:", err)
        return
    }

    network := raw.Masked() // 接收返回值；不会修改 raw
    fmt.Println("raw:", raw)
    fmt.Println("network:", network)
    fmt.Println("contains:", raw.Contains(candidate), network.Contains(candidate))
    fmt.Println("same value:", raw == network)

    // 以网段作为键时，统一使用规范化值，避免同一网络出现多个键。
    labels := map[netip.Prefix]string{network: "demo"}
    fmt.Println("raw key:", labels[raw])
    fmt.Println("network key:", labels[raw.Masked()])
}

按 API 语义推导，raw 保留 192.0.2.157/24，network 为 192.0.2.0/24，两次 Contains 都为 true，而值比较为 false。labels 只存入规范前缀，因此以 raw 取值为空字符串，以 raw.Masked() 取值为 demo。这里给出的是语义预期，没有声称本地执行结果。

能力理据：Prefix 保存地址与长度，Contains 使用前缀位

Prefix 把一个地址与前缀位数结合起来，地址中可以保留主机位。以 /24 的 IPv4 前缀为例，前 24 位决定网络，后面的 8 位是主机部分。保留主机部分，能让程序表示“这个地址及其网络长度”；需要纯网络表示时再调用 Masked。

Contains 判断的是目标地址与前缀的网络位是否一致，而不是把目标地址和 Prefix.Addr() 作完整相等比较。因此 192.0.2.157/24 能包含 192.0.2.23，不需要先把 .157 改成 .0。对于合法前缀，Masked 清除的是前缀长度以外的位，不改变它代表的地址集合。

对现有代码的影响：集合相同不代表值相等

Prefix 值可以用于比较和作为 map 键，但相等比较关注完整表示，不会自动以“地址集合相同”为等价关系。两个保留了不同主机位的 /24 前缀，可以拥有相同的 Contains 结果，却占据两个不同的 map 条目。

比如配置 A 写 .157/24、配置 B 写 .23/24，如果业务意思都是同一网段，统一成 .0/24 有助于避免重复记录。若业务还需要用户输入的主机地址，就应另存原值，不能只剩下规范化网段。

接入建议：在配置边界统一规范前缀

如果系统字段明确表示网络，可在解析成功后执行 p = p.Masked()，再写入以 Prefix 为键的集合。读取、去重和查询应复用同一约定。Masked 返回一个值，单写 p.Masked() 并丢弃返回值不会修改原变量。

PrefixFrom 不清除地址主机位；Addr.Prefix 则会按指定长度生成掩码后的前缀，并返回错误信息。不要因为构造方式变化，误以为 Contains 的比较规则也变化了。这里是能力分工的解释，并非某次新版本改变了 Contains 行为。

最小排查：Masked 不能修复地址族不一致

当 IPv4 前缀包含判断为 false 时，首先确认目标真的是 IPv4，而不是 IPv4 映射的 IPv6 地址。后者在 netip 中仍有不同的地址族语义。若业务规定把这类目标当 IPv4，可显式对目标调用 Unmap；这属于输入规则，不是 Masked 的功能。不要在未明确含义时把 IPv6 前缀的位数直接套给解映射后的 IPv4 地址。

带 IPv6 zone 的目标地址也会令 Contains 返回 false。是否接受去除 zone 后的地址应由业务决定，不能为得到 true 就静默删除范围信息。零值 Addr、无效 Prefix 则应在输入阶段处理；无效前缀调用 Masked 也不会变成有效网络。

• 解析错误是否被忽略，是否意外留下零值？
• 前缀位数是否符合预期，/32 是否原本就只表示一个 IPv4 地址？
• 目标与前缀地址族是否一致，是否存在映射地址或 zone？
• 失败的是 Contains，还是 map 查找、字符串对比和去重？

Masked 会修改 Prefix 的前缀长度吗？

对合法前缀，它保留长度，只把主机位清零。必须接收其返回值。

Contains 会排除 IPv4 网络地址或广播地址吗？

它做前缀集合包含判断，不额外判断某个地址在具体网络中能否分配给主机。地址用途规则应另行处理。

为什么规范化后 map 还是查不到？

检查存入和查询是否都用了相同规范化约定，再确认地址族及前缀长度；只规范化一侧不会改写已有键。

参考：Contains 地址包含规则；Masked 与规范前缀；netip 官方实现。