Go netip 和 net.ParseIP 返回类型有什么差异

我在把一个旧的 IP 白名单结构迁到 net/netip 时，最先遇到的不是解析失败，而是函数返回类型突然变了：net.ParseIP 给的是 net.IP，netip.ParseAddr 给的是 netip.Addr 和 error。这不是同一个类型的两种写法，而是两套数据模型。

简单记忆：需要兼容旧的 net 接口时保留 net.ParseIP；新代码需要可比较、不可变、能直接作为 map key 的地址值时优先使用 netip.ParseAddr。两者都能解析普通 IPv4 和 IPv6，但失败信号、IPv4 的内部表示和 IPv6 zone 的支持不同。

先把两个返回值放回数据模型

net.IP 的定义本质上是 []byte。它适合和历史网络 API 一起使用，但切片不能直接用 == 比较，也不能直接作为 map key。netip.Addr 是标准库定义的值类型，官方文档明确说明它不可变、可比较，因此可以直接比较或作为 map key。

最小的签名对比如下。示例里的注释说明了真正需要注意的类型和错误处理，不依赖某一次运行输出。

package main

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

func main() {
	legacy := net.ParseIP("192.0.2.1")
	modern, err := netip.ParseAddr("192.0.2.1")
	if legacy == nil || err != nil {
		// 旧 API 用 nil 表示失败，新 API 用 error 表示失败。
		return
	}

	fmt.Printf("legacy=%T modern=%T valid=%v\n", legacy, modern, modern.IsValid())
}

真正的差异在失败信号和 IPv4 表示

net.ParseIP 失败时返回 nil，不携带错误位置或原因。成功解析 IPv4 后，它返回 16 字节的 IPv4-mapped IPv6 形式；所以不要把 len(ip) == 4 当成“这是 IPv4”的可靠判断，通常应使用 ip.To4() != nil。

netip.ParseAddr 失败时返回零值地址和 error。零值 netip.Addr{} 不是 0.0.0.0，应通过 IsValid 或错误值判断。它还接受带 zone 的 IPv6，例如 fe80::1%eth0；旧的 net.ParseIP 不接受带 zone 的地址。

package main

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

func main() {
	oldIP := net.ParseIP("192.0.2.1")
	addr, err := netip.ParseAddr("fe80::1%eth0")
	if oldIP == nil {
		// ParseIP 只能用 nil 判断失败，成功的 IPv4 还可能是 16 字节映射值。
		return
	}
	if err != nil || !addr.IsValid() {
		// ParseAddr 同时返回错误和地址值，生产代码应优先处理 err。
		return
	}
	fmt.Println(oldIP.To4() != nil, addr.Zone())
}

按调用方选择，而不是按函数名迁移

如果下游函数签名仍然接收 net.IP，继续使用 net.ParseIP 或在边界处转换，不要为了“新”而把整个旧链路强行改掉。需要把地址放进 map[netip.Addr]struct{}、做稳定比较，或者保留 IPv6 zone 时，netip.ParseAddr 更自然。

从旧值迁移到新值时，可以使用 netip.AddrFromSlice。它要求切片长度为 4 或 16，并返回 (Addr, bool)；不能把任意字节切片直接转换成可信地址。反向适配则使用 Addr.AsSlice()，并在接口边界明确谁拥有返回的字节切片。

迁移时最容易踩的三个坑

第一，不要用 net.IP == other 比较地址；切片只能比较 nil，地址相等应使用 IP.Equal，或者迁移到可比较的 netip.Addr。第二，不要把 Addr{} 当作未指定地址，未指定地址应使用 netip.IPv4Unspecified() 或 netip.IPv6Unspecified()。第三，若系统会传递接口 zone，不能在转换到 net.IP 时悄悄丢掉 zone，因为普通 net.IP 只表达地址字节，不表达作用域名称。

我的选择标准是：新业务模型优先用 netip.Addr，旧接口边界保留 net.IP。真正需要改的通常只是解析入口和集合类型，网络连接、CIDR 或第三方接口仍按它们要求的类型在边界转换。

相关问题

net.ParseIP 为什么返回 16 字节的 IPv4？ 因为标准库把 IPv4 结果规范化为 IPv4-mapped IPv6 形式，使用 To4 判断 IPv4 语义。

netip.ParseAddr 失败后能不能只看 Addr？ 不建议。应先处理 error，再使用有效的 Addr；零值不是一个可用 IP。

netip.Addr 能直接替代所有 net.IP 吗？ 不能。它适合新代码和值语义，旧 API 仍可能要求 net.IP，应在明确的适配边界转换。

官方参考：https://pkg.go.dev/net/netip、https://pkg.go.dev/net#ParseIP