Go netip.Addr.IsPrivate 判断私有地址范围的实现方式

在 Go 中判断一个地址是否属于常见私有网段，推荐先用 netip.ParseAddr 验证文本，再调用 Addr.IsPrivate()。它按 RFC 1918 识别 IPv4 的 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16，按 RFC 4193 识别 IPv6 的 fc00::/7。解析失败是输入问题，合法但非私有是分类结果，两者不要混在一个布尔值里处理。

IsPrivate 覆盖哪些地址范围

IsPrivate 的语义比“是不是内网”更精确：它只回答地址是否落在标准定义的私有范围内。IPv4 看三段 RFC 1918 网段，IPv6 看唯一本地地址的 fc00::/7。回环地址、未指定地址、链路本地地址和组播地址分别有 IsLoopback、IsUnspecified、IsLinkLocalUnicast、IsMulticast 等方法，不应该把它们都归入私有地址。

先解析地址，再执行分类判断

不要用字符串前缀判断私网，例如把 192.168.1.20 和 192.1680.20 交给同一套规则。ParseAddr 会把格式错误留在输入层，成功后再调用 IsPrivate，调用方就能区分“无法识别”和“识别为公网地址”。

package main

import (
	"fmt"
	"net/netip"
)

func classify(raw string) (string, error) {
	// 先解析并验证文本，避免用字符串前缀代替地址语义。
	addr, err := netip.ParseAddr(raw)
	if err != nil {
		return "invalid-address", fmt.Errorf("parse IP %q: %w", raw, err)
	}

	// IsPrivate 只负责标准私有范围分类，不承担授权决策。
	if addr.IsPrivate() {
		return "private", nil
	}
	return "non-private", nil
}

func main() {
	for _, raw := range []string{"192.168.10.8", "2001:db8::8", "bad-ip"} {
		kind, err := classify(raw)
		if err != nil {
			// 生产代码可将原始输入替换为请求 ID，避免日志泄露敏感地址。
			fmt.Printf("%s: %v\\n", kind, err)
			continue
		}
		fmt.Printf("%s: %s\\n", raw, kind)
	}
}

这里的返回值有意把结果分成三类：invalid-address、private 和 non-private。如果业务只需要布尔值，也建议在这一层之后再映射，避免把格式错误误当成公网地址放行。

IPv4 映射地址先确定协议边界

IPv4-mapped IPv6 形式类似 ::ffff:192.168.1.8。它在数据结构上是 IPv6 地址，但表达的是一个 IPv4 地址。Go 的 netip 保留了这种表示，业务如果要和“纯 IPv4 输入”采用同一条规则，可以先用 Unmap 统一；如果日志、ACL 或协议需要保留原始地址族，则应保留原值并单独记录映射关系。

func privateAfterUnmap(raw string) (bool, error) {
	// ParseAddr 先保留输入的原始地址族和 zone 语义。
	addr, err := netip.ParseAddr(raw)
	if err != nil {
		return false, fmt.Errorf("parse mapped address: %w", err)
	}

	// Unmap 只在业务需要把 IPv4-mapped IPv6 归一为 IPv4 时使用。
	return addr.Unmap().IsPrivate(), nil
}

Unmap 不是“更安全”的判断方式，而是表示层归一化。是否调用它取决于上游协议：如果输入来自支持两种地址表达的代理链，归一化通常更容易写统一策略；如果需要审计原始连接地址，就同时保存原始值和归一化值。

把分类结果交给策略而不是当成安全授权

官方文档明确提醒，IsPrivate 不描述地址的安全属性，不能直接用来做访问控制。一个私有地址可能来自不可信的网络路径；一个公网地址也可能通过认证代理访问受保护资源。更稳妥的设计是：地址分类用于选择日志标签、路由分支或默认策略，认证、授权、网络隔离和请求来源校验继续由独立层完成。

• 输入层：解析失败返回明确错误，设置长度和格式限制。
• 分类层：组合 IsPrivate、IsLoopback、IsUnspecified 等互不替代的判断。
• 策略层：用身份、权限和网络控制决定是否允许，而不是只看一个地址布尔值。

相关问题

IsPrivate 会把 127.0.0.1 当成普通私网吗？

不要依赖这种推断。回环语义应使用 IsLoopback 单独判断，并按业务把回环、私有、链路本地和未指定地址分开记录。

解析失败时能不能直接当成公网地址？

不建议。解析失败说明输入没有通过地址格式检查，应该走拒绝、清洗或人工排查分支，而不是与合法公网地址共享策略。

IsPrivate 能替代 SSRF 防护吗？

不能。它只覆盖 RFC 1918 和 RFC 4193 私有范围，不能替代 DNS 解析后的地址校验、重定向控制、认证授权和网络隔离。