Go netip.AddrPort.AppendBinary 怎样编码地址和端口到已有缓冲区

官方文档：https://pkg.go.dev/net/netip#AddrPort.AppendBinary

如果要把一个 IP 地址和端口写进缓存键、二进制记录或自定义消息，直接拼接字符串会引入格式化和再解析。netip.AddrPort.AppendBinary 更适合这个场景：它把地址的二进制表示追加到传入的 []byte，再追加 2 个字节保存端口；端口使用小端序。传入无效地址时返回错误，成功后拿到扩展后的切片。

一、先确认 AppendBinary 的输出契约

AddrPort.AppendBinary 先委托地址对象追加二进制内容，再把端口以小端序追加到末尾。IPv4 和 IPv6 的长度不同，所以结果不是固定的 6 字节：IPv4 通常是 4+2 字节，IPv6 通常是 16+2 字节。零值 Addr 无效，遇到这类输入时应先处理返回的错误。

还要注意它不是文本编码。192.0.2.10:8080 的文本形式便于日志阅读，而二进制形式更适合做稳定的字节键。两者用途不同，不要把 AppendTo 或 AppendText 的文本结果与 AppendBinary 混用。

二、把编码追加到已有缓冲区

追加 API 的关键是把调用者已有的前缀传进去，并接住返回值。返回值可能指向扩容后的底层数组，因此不能忽略它。下面的示例把一个业务前缀和地址端口编码拼在一起，同时保留错误处理。

package main

import (
	"fmt"
	"net/netip"
)

// appendEndpointKey 把业务前缀、IP 地址和端口放进同一个字节键。
func appendEndpointKey(prefix []byte, endpoint netip.AddrPort) ([]byte, error) {
	// 预留少量空间只是减少常见情况下的扩容，不能替代接收返回值。
	buf := append(prefix, 0, 0, 0, 0, 0, 0)
	buf = buf[:len(prefix)]
	encoded, err := endpoint.AppendBinary(buf)
	if err != nil {
		// 无效 AddrPort 不应继续生成一个看似合法的键。
		return nil, fmt.Errorf("编码地址端口失败: %w", err)
	}
	return encoded, nil
}

func main() {
	endpoint := netip.MustParseAddrPort("192.0.2.10:8080")
	key, err := appendEndpointKey([]byte("node:"), endpoint)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%x\\n", key)
}

这里的前缀仍然保留在结果开头，编码器只负责从当前长度继续追加。示例用 MustParseAddrPort 处理硬编码测试值；如果地址来自请求、配置或文件，应改用 ParseAddrPort，把解析错误和追加错误分别返回给上层。

三、用 UnmarshalBinary 做边界检查

编码和解码必须使用同一套布局。UnmarshalBinary 期待的就是 AddrPort.MarshalBinary 或 AppendBinary 产生的形式，并会检查输入长度和地址部分。不要先把最后两个字节当端口，再盲目把前面的内容当 IPv4；IPv4、IPv6 以及带 zone 的地址都应交给标准库处理。

package main

import (
	"fmt"
	"net/netip"
)

// decodeEndpoint 只接受标准库生成的 AddrPort 二进制布局。
func decodeEndpoint(data []byte) (netip.AddrPort, error) {
	var endpoint netip.AddrPort
	if err := endpoint.UnmarshalBinary(data); err != nil {
		// 长度不足、地址字节不合法等情况都在这里统一返回。
		return netip.AddrPort{}, fmt.Errorf("解码地址端口失败: %w", err)
	}
	return endpoint, nil
}

func main() {
	original := netip.MustParseAddrPort("2001:db8::10:443")
	data, err := original.AppendBinary([]byte{'K', '1'})
	if err != nil {
		panic(err)
	}

	// 解码时传入纯编码段，业务前缀要由协议层先剥离。
	recovered, err := decodeEndpoint(data[2:])
	if err != nil {
		panic(err)
	}
	fmt.Println(recovered.String())
}

示例中的 data[2:] 是因为前面人为放了两个业务字节；真实协议应由自己的字段长度或记录边界决定如何剥离前缀。不要在解码函数内部写死“减 6”之类的规则，因为 IPv6 地址部分可能占 16 字节。

四、落到可复用的小项目函数

在实际项目里，可以把“业务前缀”和“AddrPort 编码段”作为两个明确字段管理。编码函数只追加，解码函数只接收已经切分好的二进制段，这样既能复用缓冲区，也能把协议边界留在协议层。若需要跨语言互通，还应把地址长度、端口字节序和错误处理写进协议文档，不能只依赖函数名猜测。

相关问题

AppendBinary 会不会把已有切片清空？

不会。它从传入切片当前长度继续追加；调用者需要使用返回的切片。

端口为什么不是网络字节序？

该 API 的二进制契约明确使用小端端口。如果协议要求大端，应在协议层单独转换，不要把两种布局混在一起。

IPv4 和 IPv6 可以用同一个解码函数吗？

可以。UnmarshalBinary 会根据地址部分的标准二进制形式处理两种地址族，调用方只需要保证传入完整编码段。