Go netip.Addr.IsLoopback 怎样区分本机回环地址和普通地址

我在处理本地回调、测试白名单时，最容易踩的坑是把“字符串是 127.0.0.1”当成了“地址属于回环范围”。更稳的写法是先用 netip.ParseAddr 得到不可变、可比较的 netip.Addr，再调用 IsLoopback。这样 127.0.0.1 和 ::1 走同一套分类逻辑，普通公网地址则不会被误判。

官方地址：https://pkg.go.dev/net/netip@go1.27.3#Addr.IsLoopback

结论先说：解析失败要单独返回错误；解析成功后用 IsLoopback 判断回环，用 IsUnspecified 判断 0.0.0.0 或 ::，不要把零值 Addr{} 当成任何一种可用地址。

先把文本转换成可分类的 Addr

netip.Addr 是小型值类型，支持比较且不可变。ParseAddr 能解析点分十进制、IPv6，以及带 zone 的 IPv6 文本；它返回的错误应该和“不是回环地址”区分开，否则调用方很难知道是输入坏了，还是输入有效但属于普通地址。

package main

import (
	"fmt"
	"net/netip"
)

func main() {
	inputs := []string{"127.0.0.1", "::1", "192.0.2.10", "bad-ip"}
	for _, raw := range inputs {
		ip, err := netip.ParseAddr(raw)
		if err != nil {
			// 解析失败不是“普通地址”，应交给输入错误分支处理。
			fmt.Printf("%s -> parse error: %v\n", raw, err)
			continue
		}
		// IsLoopback 负责地址分类，避免维护容易漏项的字符串白名单。
		fmt.Printf("%s -> loopback=%t\n", raw, ip.IsLoopback())
	}
}

这个判断的关键是先检查 err，再读取布尔结果。127.0.0.1 和 ::1 都是有效回环地址；192.0.2.10 是有效但非回环地址；bad-ip 则根本没有进入分类阶段。

IsLoopback 判断的是回环语义，不是某一个字符串

回环判断适合放在“是否允许本机访问”的分类层，而不是散落在业务分支中手写多个字符串。函数返回 bool，本身不告诉你原始文本是否来自 IPv4 或 IPv6；如果日志或策略还关心地址族，可以配合 Is4、Is6 和 Is4In6 记录结构化信息。

要注意，Is4 对 IPv4-mapped IPv6 返回 false，而 Is4In6 专门识别 ::ffff:0:0/96 这一映射形式。它们回答的是地址表示问题，IsLoopback 回答的是回环分类问题，不能互相替代。

func classify(raw string) (string, error) {
	ip, err := netip.ParseAddr(raw)
	if err != nil {
		return "invalid", err
	}
	if !ip.IsValid() {
		// 零值 Addr 不是有效 IP；这里只保留防御性分支。
		return "zero-addr", nil
	}
	if ip.IsLoopback() {
		// 回环判断用于本机访问策略或测试地址分类。
		return "loopback", nil
	}
	if ip.IsUnspecified() {
		// 未指定地址代表绑定范围，不等于本机回环地址。
		return "unspecified", nil
	}
	return "ordinary", nil
}

在服务端访问控制里，建议把 invalid、loopback、unspecified 和 ordinary 映射成明确的策略，而不是把所有 false 都当成“外部地址”。这样输入错误和策略拒绝才不会混在一起。

映射地址、未指定地址和零值要分开

0.0.0.0 与 :: 是有效的未指定地址，应该用 IsUnspecified 识别；它们不是回环地址。相反，Addr{} 是未初始化的零值，IsValid 返回 false，也不应拿来表示“任意本机地址”。

IPv4-mapped IPv6 常见于解析器或网络边界，例如形如 ::ffff:127.0.0.1 的表示。现代 Go 的 netip 文档提供了 Is4In6 和 Unmap 来识别、还原这种表示；如果项目仍运行在较早的 Go 版本，应该把 net/netip 的已知修复纳入升级计划，不要只在业务层补字符串特例。

把分类函数放在策略入口

我更愿意让 HTTP 处理器、代理白名单和测试夹具都调用同一个分类函数：入口负责解析，策略负责决定是否放行，日志负责记录地址族和原始输入。这样后续从字符串地址迁移到 netip.Addr 时，只改一处边界代码。

如果代码需要支持受影响的旧 Go 版本，升级优先级应高于继续堆叠映射地址特例。官方漏洞记录曾指出，早期版本的若干 netip.Addr.Is... 方法对 IPv4-mapped IPv6 的判断存在问题；当前工程应明确最低 Go 版本，并把版本策略写进模块与发布说明。

常见问题

IsLoopback 返回 false，能说明地址一定是公网地址吗？

不能。它可能是普通内网地址、未指定地址、组播地址、无效输入，或尚未经过正确解析的值。先区分解析错误，再按 IsUnspecified、IsPrivate 等独立语义判断。

为什么不直接比较 ip.String()？

字符串比较容易漏掉 IPv6、映射地址和表示差异。Addr 提供了面向地址语义的分类方法，业务代码只需要保留真正关心的策略。

Is4 和 Is4In6 应该怎么选？

Is4 判断原生 IPv4 表示，Is4In6 判断 IPv4-mapped IPv6 表示。它们用于记录地址形态；是否回环仍由 IsLoopback 判断。

这次实践最后留下的规则很简单：解析错误不要伪装成普通地址，回环不要靠字符串白名单，未指定地址不要当成本机地址，零值更不能进入放行策略。把这些边界集中在 netip.Addr 分类层，调用方会清楚很多。