Go net.IP 判断 IPv4 时为什么不能只看字符串

用 Go 的 net.ParseIP 判断 IPv4 时，最容易踩的坑是把字符串显示结果当成地址类型。ParseIP("192.0.2.1") 返回的 net.IP 仍是 16 字节，只是它采用了 IPv4-mapped IPv6 的统一表示；真正应该使用的是 ip != nil && ip.To4() != nil。这样既能识别普通 IPv4，也能识别 ::ffff:192.0.2.1，而普通 IPv6 会返回 nil。

ParseIP 返回的 IPv4 为什么长度不是 4

net.IP 本质上是字节切片。Go 的 ParseIP 为了让 IPv4 和 IPv6 使用统一的 16 字节容器，会把 IPv4 放进 IPv4-mapped IPv6 形式。因此下面这些输入虽然文本不同，解析结果的长度都不能简单推出“这是普通 IPv6”：

所以，len(ip)==4 只能描述某个已经是 4 字节切片的状态，不能覆盖 ParseIP 的返回约定。相反，直接看 String() 也不严谨，因为 IPv4-mapped 地址在显示时可能被格式化成点分十进制，显示层和类型层不是一回事。

用 To4 判断 IPv4，别用 String 反推类型

IP.To4() 的语义很直接：如果接收者是 IPv4，返回 4 字节表示；如果不是 IPv4，返回 nil。封装成函数时，先挡住非法输入，再判断转换结果：

package main

import "net"

// isIPv4 只回答地址能否按 IPv4 使用，不负责保留输入文本。
func isIPv4(text string) bool {
	// ParseIP 失败时返回 nil，先排除非法地址。
	ip := net.ParseIP(text)
	// To4 对 IPv4 和 IPv4-mapped IPv6 都返回非 nil。
	return ip != nil && ip.To4() != nil
}

这里有两个边界。第一，ip != nil 只能说明文本是某种合法 IP，不能说明它是 IPv4；合法 IPv6 同样会得到非 nil。第二，To4() 的结果不要直接和输入字符串比较，它是用于地址族判断和后续 4 字节操作的规范化值。

如果你需要把地址分类后交给不同逻辑，可以把判断写成显式分支：

func family(text string) string {
	// 非法输入与 IPv6 不应混成同一个结果。
	ip := net.ParseIP(text)
	if ip == nil {
		return "invalid"
	}
	if ip.To4() != nil {
		return "ipv4"
	}
	// ParseIP 成功且 To4 为 nil 时，当前示例按 IPv6 处理。
	return "ipv6"
}

这个分类适合做白名单、协议选择或日志标签。若后续要判断 IPv6 是否为回环、链路本地等，还应继续使用 net.IP 提供的语义方法，不要把一串冒号或点号当作业务规则。

显示形式、地址类型和原始输入要分开

工程里常把地址放进日志、缓存键或请求头，建议先明确三个问题：需要展示什么、需要判断什么、需要保留什么。ip.String() 解决可读展示；ip.To4() 和 ip.To16() 解决规范化判断；原始字符串只有在业务需要追踪用户输入形式时才保存。

• 只判断能否走 IPv4 分支：使用 ip != nil && ip.To4() != nil。
• 需要稳定的 4 字节值：保存 v4 := ip.To4()，并在使用前确认它不是 nil。
• 需要区分原始输入写法：同时保存 text，不要从 String() 反推。

例如，192.0.2.1 与 ::ffff:192.0.2.1 在 IPv4 业务分支里通常应视为同一地址族；但如果日志审计要求记录客户端原始输入，两者仍应保留不同的原文。这是业务字段设计问题，不是 To4() 判断失效。

常见问题

为什么 ParseIP 不直接返回 4 字节 IPv4？

它使用统一的 16 字节表示，使 IPv4、IPv4-mapped IPv6 和 IPv6 可以共享 net.IP API。需要 4 字节时再调用 To4()。

To4 返回 nil 是不是说明 IP 一定非法？

不是。对合法的普通 IPv6，ParseIP 非 nil 但 To4() 为 nil；只有 ParseIP 本身返回 nil 才表示文本没有被解析成 IP。

能不能用 strings.Contains 判断 IPv4？

不建议。点号、冒号和 IPv4-mapped IPv6 的显示规则都可能让字符串判断失去边界，使用标准库的解析和转换语义更可靠。

官方文档可从 net.ParseIP、net.IP.To4 以及 net 包源码继续核对。记住一句话：字符串用于展示，To4() 用于判断 IPv4。