Go hex.AppendEncode 怎样复用目标缓冲区

Go 的 hex.AppendEncode 适合把一段字节的十六进制表示直接追加到已有的 []byte。它返回扩展后的切片，因此既能保留目标切片前缀，也能在容量足够时复用底层数组；真正需要注意的是，十六进制编码长度固定为源数据的两倍，循环复用时还要区分“下一轮继续写”和“结果需要长期保留”这两种场景。

官方文档：https://pkg.go.dev/encoding/hex#AppendEncode

把 hex.AppendEncode(dst, src) 当作一次“追加操作”使用：接住返回值，用 hex.EncodedLen(len(src)) 预留空间；如果下一轮还要复用同一块内存，就把切片切回零长度，但不要把仍在使用的结果直接覆盖。

• 返回值：是追加后的 []byte，不是写入字节数。
• 空间：每个源字节对应两个十六进制字符，容量可用 hex.EncodedLen 计算。
• 复用：复用的是底层数组，不是自动复制一份独立结果。

追加编码和覆盖编码不是一回事

hex.Encode 要求调用方先准备好目标空间，然后把编码结果写入目标切片；hex.AppendEncode 则沿用 append 的切片语义，把结果接在 dst 当前长度之后。无论 dst 是否已经有前缀，调用后都应使用返回值。

package main

import (
	"encoding/hex"
	"fmt"
)

func main() {
	prefix := []byte("trace=")
	payload := []byte{0x2a, 0x7f, 0xc0}

	// 预留前缀和编码结果的总空间，避免中途再次扩容。
	buf := make([]byte, 0, len(prefix)+hex.EncodedLen(len(payload)))
	buf = append(buf, prefix...)
	// AppendEncode 返回扩展后的切片，不能忽略返回值。
	buf = hex.AppendEncode(buf, payload)

	fmt.Printf("%s\n", buf) // 输出 trace=2a7fc0
}

这里的目标切片先装入 trace=，再追加 6 个十六进制字符。即使容量不足，AppendEncode 也会按切片规则得到一块更大的底层数组；提前计算容量的价值，是让容量规划和文章中的数据边界保持明确，而不是改变编码结果。

用 EncodedLen 把容量算在调用之前

官方文档定义 EncodedLen(n) 的结果为 n * 2。因此，单次编码可以使用 make([]byte, 0, hex.EncodedLen(len(src)))；如果目标切片已经有前缀，则再加上前缀长度。这里预留的是容量，不是长度，不能把切片直接写成长度已经包含空白位置的形式。

func encodeToken(src []byte) []byte {
	// 十六进制输出每个源字节占两个位置，长度从 0 开始。
	dst := make([]byte, 0, hex.EncodedLen(len(src)))
	// 追加函数可能返回新的切片，必须重新接收。
	return hex.AppendEncode(dst, src)
}

func encodeWithLabel(label string, src []byte) []byte {
	// 前缀使用字节长度，编码部分使用 EncodedLen 计算。
	dst := make([]byte, 0, len(label)+hex.EncodedLen(len(src)))
	dst = append(dst, label...)
	return hex.AppendEncode(dst, src)
}

如果调用方只需要一个最终字节切片，这种写法就足够了。若还要把结果转换成字符串，string(dst) 会产生字符串值；不要为了“复用”而保存一个之后还会继续改写的可变切片引用。

循环复用缓冲区时，先判断结果的生命周期

批量编码的关键不是把每个结果都塞进同一切片，而是明确结果是否只在当前迭代内使用。当前结果用完后，可以用 buf[:0] 保留容量并从头追加；如果结果要交给异步任务、放入集合或跨过下一轮循环，就必须复制一份独立数据。

func encodeBatch(parts [][]byte) [][]byte {
	// 这块缓冲区只服务于当前迭代，容量会在各轮之间保留。
	buf := make([]byte, 0, 64)
	results := make([][]byte, 0, len(parts))

	for _, part := range parts {
		// 清零长度但保留底层数组，下一轮从同一空间开始追加。
		buf = buf[:0]
		buf = hex.AppendEncode(buf, part)
		// 结果要跨过下一轮继续使用，所以复制而不是保存 buf 的别名。
		copyOfResult := append([]byte(nil), buf...)
		results = append(results, copyOfResult)
	}
	return results
}

如果处理逻辑在当前循环内立即消费编码结果，可以省略复制；如果把 buf 直接追加到 results，下一轮的写入可能覆盖之前看到的内容。容量复用解决的是分配次数，不能替代结果所有权设计。

容量不足时让追加语义自然扩容

预留容量是一种优化，不是正确性的前提。调用方不确定源数据大小时，可以直接把已有切片交给 AppendEncode，由切片追加逻辑处理容量不足的情况。需要避免的是为了追求“零分配”而手写一套容易出错的边界计算：先保证返回值被接住，再根据热点路径决定是否预估容量。

还有一个容易混淆的点：len(dst) 表示当前已有数据的长度，cap(dst) 表示底层数组能容纳的上限。追加编码始终从长度位置开始写，不会把已有前缀当成空白空间。如果要从头重用，应显式使用 dst = dst[:0]，并确认旧内容已经不再被读取。

常见问题

hex.AppendEncode 会返回编码了多少个字节吗？

不会。它返回追加后的 []byte；编码后的新增长度可以用 hex.EncodedLen(len(src)) 计算。

为什么调用 AppendEncode 后原来的 dst 没有变化？

最常见原因是忽略了返回值。追加操作可能因为容量不足而返回指向新底层数组的切片，应该写成 dst = hex.AppendEncode(dst, src)。

buf[:0] 是不是清空了底层数据？

它只把长度切回 0，通常仍保留原底层数组。下一次追加会覆盖旧区域，因此跨轮保存的结果必须先复制。

怎样判断预留容量够不够？

对于当前追加操作，比较 cap(dst)-len(dst) 与 hex.EncodedLen(len(src)) 即可；但一般无需手动扩容，直接追加更简单，只有明确的批量热点路径才值得提前规划容量。