Go encoding/hex AppendEncode 怎样把字节追加为十六进制文本

在需要把二进制字段拼进日志、协议文本或缓存键时，encoding/hex.AppendEncode 很适合替代“先算长度、再调用 Encode”的手写组合：它把 src 编成小写十六进制字符，追加到 dst，并返回扩展后的切片。最容易踩的坑是忘记接收返回值，或者把 cap(dst) 误当成已经写入的长度。

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

本文只讨论一次性的字节切片追加，不展开 NewEncoder 的流式写入，也不讨论十六进制字符串解码。

先看 AppendEncode 的输入与返回值

AppendEncode(dst, src) 的两个参数职责不同：dst 是已有结果，可能包含前缀；src 是待编码的原始字节。函数返回新的切片视图，内容是“原来的 dst + 编码后的 src”。如果底层容量不够，返回值可能指向新的数组，所以调用后必须使用返回值。

package main

import (
    "encoding/hex"
    "fmt"
)

func main() {
    // dst 先放业务前缀，src 是需要转成十六进制的原始字节。
    dst := []byte("id=")
    src := []byte{0x2a, 0x7f, 0xa0}

    // 返回值代表追加完成后的切片，不能只依赖原来的 dst 变量。
    dst = hex.AppendEncode(dst, src)
    fmt.Printf("%s len=%d cap=%d\\n", dst, len(dst), cap(dst))
}

这个例子中，src 的 3 个字节会产生 6 个字符，结果文本是 id=2a7fa0。十六进制编码不会把一个字节变成一个字符，而是用高四位和低四位分别映射到字符表，因此输出长度始终是输入字节数的两倍。

用预留容量追加十六进制文本

如果调用点已经知道待编码数据的大小，可以用 hex.EncodedLen 预留空间，再把已有内容切到目标写入区。这不是必须步骤，但在循环拼接或批量构造协议字段时，能减少反复扩容的机会。无论是否预留，最终都要接住 AppendEncode 的返回值。

package main

import (
    "encoding/hex"
    "fmt"
)

func appendHexField(dst, src []byte) []byte {
    // 预留 src 编码后的确切字节数：每个源字节对应两个十六进制字符。
    need := hex.EncodedLen(len(src))
    if cap(dst)-len(dst) 

这里的 need 是新增字符数，不是最终总长度；已有前缀仍由 len(dst) 计入。标准库实现内部也会按 EncodedLen(len(src)) 计算增长量，因此这条关系可以作为排查长度问题的第一依据。

实践中不建议为了“保证零分配”而手动复制所有逻辑。若只是偶尔拼接，直接调用 hex.AppendEncode 更清楚；只有在明确的批量路径中，才值得提前安排容量。

区分容量不足、旧数据和编码格式

len 表示当前结果中可读的字节数，cap 表示底层数组从切片起点起可容纳的上限。容量大于长度，只说明尾部可能还有空间，并不表示尾部已经是结果的一部分。调用 AppendEncode 后，必须用返回切片的长度读取新增内容。

另外，AppendEncode 输出的是小写十六进制字符。若协议要求大写，可以在追加后统一转换，或者选择更适合该协议的编码层；不要把“字节转十六进制”和“字母大小写策略”混成容量问题。空的 src 不新增内容，返回切片仍保留 dst 的现有数据。

延伸问答

AppendEncode 会覆盖 dst 原来的内容吗？

不会。它从 dst 当前长度之后追加，原有可读内容仍保留；但如果调用者随后使用了错误的切片边界，仍可能误读结果。

为什么不能写成只调用不接收返回值？

容量不足时函数可能分配新底层数组；即使这次刚好复用了原数组，忽略返回值也会让代码依赖偶然的容量状态。

AppendEncode 与 Encode 的主要区别是什么？

Encode 要求调用者先提供足够大的目标区域，并返回写入字节数；AppendEncode 负责在已有切片后增长并返回扩展后的切片，更适合组合多个字段。

参考：https://pkg.go.dev/encoding/hex、https://go.dev/src/encoding/hex/hex.go。文中配图均为原创静态说明图，不是本机执行截图。