Go 语言 net 包：IPMask、IPNet 与 HardwareAddr 的 JSON 序列化迁移——从 base64 到可读文本格式

本篇围绕 Go 标准库 net 包中一次典型的"向后兼容的两步走"API 变更展开：[IPMask]、[IPNet] 与 [HardwareAddr] 三个类型实现 [encoding.TextUnmarshaler] 接口（对应 issue #29678 的变更说明）。读完本文，你能理解这三个类型在 JSON 序列化中为什么曾经是难以阅读的 base64 编码、新格式如何做到"新代码能读旧数据、旧代码不受影响"，以及 netmarshal 这个 godebug 开关如何控制默认格式的最终切换。

背景：这三个类型在 JSON 里曾经长什么样

在实现 [encoding.TextUnmarshaler] 之前，Go 的 encoding/json 对这三个类型的处理完全依赖类型系统的默认规则：

• net.HardwareAddr 是 []byte 的别名类型，JSON 中会被编码为 base64 字符串（[]byte 的默认 JSON 规则）；
• net.IPMask 同样是 []byte，JSON 中也是 base64 字符串；
• net.IPNet 是一个结构体（字段 IP、Mask），JSON 中会展开为嵌套对象，其中的 Mask 字段依旧是 base64。

这种格式机器可解析，但人类几乎无法阅读。例如一个 /24 子网的掩码 255.255.255.255（4 个 0xFF 字节）在 JSON 里会呈现为：

{
  "mask": "//////8="
}

而一个 MAC 地址 00:00:5e:00:53:01 则呈现为一串无意义的 base64。对于配置导出、API 日志、故障排查等场景，这种格式非常不友好。

issue #29678 的目标就是让这三个类型的 JSON 编码变成"可读文本"（IP 地址点分十进制、MAC 的 xx:xx:xx:xx:xx:xx 形式），同时不破坏旧版本 Go 程序对新数据的读取。

核心设计：UnmarshalText 同时接受新旧两种格式

issue 变更说明 给出的方案是：本次发布先只添加 [encoding.TextUnmarshaler] 方法（即可读化"入"），该方法既能识别当前版本已生成的旧 base64 编码，也能识别计划中的新可读格式；而默认输出格式（"出"）留到后续的 Go 版本再切换。这样做的直接收益是：

• 本版本 Go 生成的 JSON（仍是 base64）可以被更早的 Go 版本读回，不受影响；
• 本版本 Go 程序已经可以读取"未来格式"的可读 JSON，为后续默认值切换铺路。

这是一个经典的两步走迁移（two-step process）：先让读写端都兼容双格式，等生态中旧程序比例足够低之后，再翻转默认输出。

源码走读：IPMask.UnmarshalText 的双格式回退

当前仓库中 src/net/ip.go 的 IPMask.UnmarshalText 完整体现了这个双格式逻辑：

// UnmarshalText implements the [encoding.TextUnmarshaler] interface.
// In older Go versions the JSON encoding of IPMask was
// that of a []byte. In order to support new Go programs reading JSON
// encodings produced by old Go programs, we support the []byte encoding.
func (m *IPMask) UnmarshalText(text []byte) error {
	var ip IP
	err := ip.UnmarshalText(text)
	if err == nil {
		if bytealg.IndexByte(text, ':') < 0 {
			ip = ip.To4()
		}
		*m = IPMask(ip)
		return nil
	}

	// IP.Unmarshal failed; try base64.

	dst := make([]byte, len(text)/4*3)
	n, ok := base64Decode(dst, text)
	if ok {
		*m = IPMask(dst[:n])
		return nil
	}

	// The base64 decode failed: return the IP.Unmarshal error.
	return err
}

调用顺序值得注意：

1. 先按 IP 文本解析：委托给 IP.UnmarshalText（内部走 ParseIP）。这里有一个细节——如果解析成功且文本中不含冒号（说明是点分十进制 IPv4），会主动 To4() 把掩码归一化为 4 字节长度，保证 255.255.255.255 解出的掩码长度正确；
2. 回退到 base64 解码：IP 文本解析失败后，尝试按 []byte 的旧 base64 编码解码，成功则直接还原字节序列；
3. 都失败时返回 IP 解析的错误，而不是 base64 的失败信息。

对应的 MarshalText（src/net/ip.go）当前仍由 netmarshalOld() 决定输出哪种格式：

func (m IPMask) MarshalText() ([]byte, error) {
	// For backward compatibility, marshal as plain []byte.
	if netmarshalOld() {
		return base64Encode(m), nil
	}
	// We don't use IP.MarshalText directly because
	// we want to preserve the length.
	addr, _ := netip.AddrFromSlice(m)
	return addr.AppendTo(nil), nil
}

注释中"不直接调用 IP.MarshalText"说明了另一个实现细节：IP.MarshalText 对 IPv4 会输出 a.b.c.d（4 字节），而掩码需要保留原始长度（IPv4 掩码 4 字节、IPv6 掩码 16 字节），所以改用 netip.Addr.AppendTo 按原始字节长度输出。

源码走读：HardwareAddr.UnmarshalText 的双格式回退

MAC 地址的实现同构，见 src/net/mac.go：

func (a *HardwareAddr) UnmarshalText(text []byte) error {
	hw, err := ParseMAC(string(text))
	if err == nil {
		*a = hw
		return nil
	}

	// ParseMAC failed: try base64.

	dst := make([]byte, len(text)/4*3)
	n, ok := base64Decode(dst, text)
	if ok {
		*a = HardwareAddr(dst[:n])
		return nil
	}

	// The base64 decode failed: return the ParseMAC error.
	return err
}

• 首选 ParseMAC：它接受冒号、连字符、点号以及无分隔符等多种写法（支持 6 字节 MAC-48/EUI-48、8 字节 EUI-64 与 20 字节 InfiniBand 地址，见 src/net/mac.go）；
• 失败后回退 base64；MarshalText 同样按 netmarshalOld() 二选一，新格式直接输出 a.String() 即 xx:xx:xx:xx:xx:xx 形式（src/net/mac.go）。

IPNet 如何实现 TextUnmarshaler

从源码结构看，net.IPNet 并没有定义自己的 MarshalText/UnmarshalText 方法。它在 JSON 中按结构体默认规则展开为 {"IP": ..., "Mask": ...} 两个字段，而这两个字段类型 net.IP 与 net.IPMask 各自都实现了 [encoding.TextUnmarshaler]（src/net/ip.go 为 IP.UnmarshalText，委托 ParseIP 解析，空文本置零值）。因此 IPNet 的"可读化"是由其组成字段的 TextUnmarshaler 能力自然组合出来的——这也解释了为什么变更说明把 IPNet 与 IPMask、HardwareAddr 并列：三者构成的整个子网对象在 JSON 中最终都变成了可读文本。

一个包含全部三个类型的示例及其新旧格式对照：

type Subnet struct {
    Gateway net.IP           `json:"gateway"`
    Mask    net.IPMask       `json:"mask"`
    Subnet  net.IPNet        `json:"subnet"`
    MAC     net.HardwareAddr `json:"mac"`
}

// 旧格式（base64，当前默认输出）
{
  "mask": "//////8=",
  "mac": "AAB+AAUTASg="
}

// 新格式（可读文本，UnmarshalText 已可解析，Marshal 默认将在后续版本切换）
{
  "mask": "255.255.255.255",
  "mac": "00:00:5e:00:53:01"
}

默认格式如何切换：netmarshal godebug 开关

控制"出"方向默认格式的是一个 godebug 设置，定义在 src/net/ip.go：

var netmarshal = godebug.New("netmarshal")

// netmarshalOld reports whether we are using the backward
// compatible marshaling for IPMask, IPNet, and HardwareAddr.
func netmarshalOld() bool {
	switch netmarshal.Value() {
	case "":
		return goversion.Version < 30
	case "0":
		if goversion.Version >= 30 {
			netmarshal.IncNonDefault()
		}
		return true
	default:
		if goversion.Version < 30 {
			netmarshal.IncNonDefault()
		}
		return false
	}
}

从 doc/godebug.md 可以看到官方对切换时间表的描述：

Go 1.28 added a new netmarshal setting that controls whether net.IPMask, net.IPNet and net.HardwareAddr ... The value netmarshal=0 will ... The value netmarshal=1 will use a readable version such as the IP address. For Go 1.28 and 1.29 the default value remains netmarshal=0. The expectation is that Go 1.30 will change the default to be netmarshal=1.

由此可以梳理出完整的迁移时间线：

阶段	行为
issue #29678 发布版本起	三个类型实现 UnmarshalText，可读格式可被读取；输出默认仍是 base64
Go 1.28	新增 netmarshal godebug，默认 0（base64）；设置 netmarshal=1 可提前启用可读输出
Go 1.30（计划）	默认值翻转为 1，可读格式成为默认输出；netmarshal=0 可回退并触发非默认值计数提示

godebug 机制的意义在于：在默认值翻转之后，用户仍能通过 GODEBUG=netmarshal=0 显式保留旧行为，IncNonDefault() 计数则会在工具链中提醒存在偏离默认值的使用。

实现细节：net 包内置的 base64 编解码

注意 UnmarshalText 中的 base64Encode/base64Decode 并不是来自 encoding/base64 包，而是 src/net/ip.go 中的内部实现。源码注释给出的理由是"so that the net package doesn't depend on encoding/base64"——net 处于标准库的底层，避免反向依赖是刻意的设计约束。这两个函数实现了标准 base64 编解码（含 = 填充校验），逻辑与 encoding/base64 的标准编码一致，因此旧格式数据的兼容性是逐字节保证的。

测试如何验证兼容性

• src/net/ip_test.go 中的 IP.UnmarshalText 用例覆盖了合法输入、非法输入与空文本置零等路径；
• 回退逻辑（文本解析失败再走 base64）由同文件中的 marshaling 相关测试用例驱动，包括 MarshalText 输出与期望字节序列的逐一比对（src/net/ip_test.go）。

这些测试确保"先新格式、后 base64"的解析顺序在边界情况（如长度非法的 IPv4 掩码、含 zone 的 IP 文本）下行为稳定。

对使用者的实践建议

1. 读取 JSON：当前版本起的 Go 程序无需任何改动即可同时读取新旧两种格式的 IPMask、IPNet、HardwareAddr 字段，双格式回退是自动的；
2. 生成 JSON：在默认翻转（Go 1.30）之前，默认输出仍是 base64。若希望现在就输出可读格式（例如对外 API 需要人类可读的掩码/MAC），可设置 GODEBUG=netmarshal=1（Go 1.28+）；
3. 跨版本互通：如果你的 JSON 需要被更早版本的 Go 程序读回，就继续保留默认 base64 输出——这正是 issue 说明中"两步走"的初衷：本版本生成的 JSON 必须仍能被旧版本 Go 读取；
4. 自定义序列化：若你在自己的 API 中已经用字符串字段表示 IP/MAC，可以直接改用这三个类型获得类型安全与 UnmarshalText 的双格式读取能力，无需手写转换。

小结

issue #29678 是一次教科书级的标准库兼容性工程：UnmarshalText 先行兼容双格式（可读文本优先、base64 回退），MarshalText 的输出格式由 netmarshal godebug 控制，默认值按 Go 1.28 引入、Go 1.30 翻转的节奏渐进迁移。对开发者而言，理解这套机制后，你就能在配置导出、API 设计、日志排查中放心地让 IP 掩码与 MAC 地址在 JSON 中以可读文本出现，同时精确控制与旧版本 Go 生态的兼容边界。