Go netip 怎么校验并规范化 IPv4 和 IPv6 地址

如果服务入口收到的是字符串形式的 IP，推荐直接使用 net/netip，不要先把它当作普通字符串比较。最小做法是调用 netip.ParseAddr：解析失败就返回错误，解析成功后用 Addr.String() 输出规范形式。遇到 ::ffff:192.0.2.1 这类 IPv4-mapped IPv6 时，再先判断 Is4In6()，必要时调用 Unmap() 统一成 192.0.2.1。

入口先用 ParseAddr 拦住非法地址

网络参数常常来自 HTTP、配置文件或日志恢复，首尾空格可以在入口处去掉，但不能为了“尽量解析”而私自替换字符。ParseAddr 支持点分十进制 IPv4、IPv6 压缩写法以及带作用域 zone 的 IPv6；失败时返回包含原因的错误。

package main

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

// parseAddress 只负责入口清洗和语法校验，不改变地址含义。
func parseAddress(raw string) (netip.Addr, error) {
    value := strings.TrimSpace(raw) // 只移除首尾空白
    if value == "" {
        return netip.Addr{}, fmt.Errorf("IP 地址不能为空")
    }
    addr, err := netip.ParseAddr(value) // 统一解析 IPv4、IPv6 和 zone
    if err != nil {
        return netip.Addr{}, fmt.Errorf("无效 IP 地址 %q: %w", raw, err)
    }
    return addr, nil
}

空字符串在这里单独报错，方便接口返回明确的参数提示。对于固定写在测试代码里的地址可以使用 MustParseAddr，但不要把它用于用户输入，因为解析失败会 panic。

先识别 IPv4-mapped IPv6，再决定归一化策略

判断地址家族时有一个容易忽略的顺序：Addr.Is4() 对 IPv4-mapped IPv6 返回 false，而 Addr.Is6() 会把它算作 IPv6。因此不能只写 if addr.Is4() { ... } else { ... }。需要先用 Is4In6() 分支。

// canonicalAddress 返回展示或存储时使用的地址字符串。
func canonicalAddress(raw string) (string, string, error) {
    addr, err := parseAddress(raw)
    if err != nil {
        return "", "", err
    }

    family := "IPv6"
    if addr.Is4In6() { // 映射地址先单独识别
        addr = addr.Unmap() // 业务需要统一家族时再还原成 IPv4
        family = "IPv4"
    } else if addr.Is4() {
        family = "IPv4"
    }
    return addr.String(), family, nil // IPv6 会使用稳定的压缩写法
}

如果业务需要保留“客户端原来提交的是映射地址”这一事实，就不要立刻覆盖原值，可以先保存 mapped := addr.Is4In6()，再复制一份地址调用 Unmap。这样日志、审计字段和规范化存储可以各自使用合适的表示。

String 统一格式，但不要误删 IPv6 zone

String() 不是简单地把输入原样返回。IPv6 会采用压缩形式，IPv4-mapped IPv6 在未调用 Unmap 时仍会保留 ::ffff: 前缀。像 fe80::1%eth0 这样的链路本地地址包含接口 zone，规范化时应保留它，否则地址可能失去可用的接口范围。

上线前用边界清单固定行为

地址规范化最好在进入缓存键、访问控制或数据库前完成，并把策略写成测试表。特别要覆盖前导零 IPv4、空字符串、映射地址和 zone。010.000.015.001 不应被当作普通十进制 IPv4 接受；这类输入应交给调用方修正，而不是在服务端猜测。

• 语法校验失败：返回参数错误，不进入后续业务。
• 普通 IPv4：直接使用 String() 作为规范键。
• 普通 IPv6：保留压缩后的 String()，不要自行实现压缩算法。
• IPv4-mapped IPv6：明确选择“保留映射”或“Unmap 后统一”，并让日志与存储策略一致。
• 带 zone 的 IPv6：保留 zone；如果业务只接受可路由地址，应在独立的策略层拒绝，而不是把 zone 静默删除。

常见问题

为什么 Is4 对 ::ffff:192.0.2.1 返回 false？

因为它仍是 IPv4-mapped IPv6。先调用 Is4In6()，需要 IPv4 形态时再调用 Unmap()。

ParseAddr 成功后还要检查 IsValid 吗？

对 ParseAddr 的成功返回值通常不必重复检查；如果地址来自可产生零值的其他路径，才应使用 IsValid() 区分无效的 Addr{}。

能不能用 MustParseAddr 处理请求参数？

不建议。它适合测试中的固定常量，外部输入应使用 ParseAddr 并把错误返回给调用方。