Go encoding/hex.EncodedLen 怎样提前分配十六进制输出缓冲区

我在把二进制字段写入日志、摘要或协议文本时，最容易先写出 hex.EncodeToString，等性能出现波动才发现中间字符串和扩容都发生在热路径。更稳妥的做法是先用 hex.EncodedLen(len(src)) 得到精确输出长度，再让 hex.Encode 直接写入目标切片。

官方地址：https://pkg.go.dev/encoding/hex#EncodedLen

十六进制编码中，输入的每个字节固定对应两个输出字符。因此 EncodedLen(n) 返回 n*2；目标切片要把长度设置成这个值，只有容量足够还不代表可以直接写入。

先把输入长度和输出长度对齐

encoding/hex 的长度关系很简单：输入 1 个字节会得到两个小写十六进制字符，输入 n 个字节就需要 2n 个字节的输出空间。这里的“字节”是 ASCII 文本字节，不是 Go 字符串里按中文字符计算的长度。

用 EncodedLen 给 Encode 准备精确长度

hex.Encode 会把编码结果写入 dst，并返回实际写入的字节数。官方文档给出的契约是：dst 至少要能容纳 hex.EncodedLen(len(src)) 个字节。最容易混淆的是切片的 len 和 cap：函数按可写长度使用 dst，仅仅预留容量但不扩展长度是不够的。

package main

import (
    "encoding/hex"
    "fmt"
)

func main() {
    src := []byte("request-id")

    // EncodedLen 给出精确的十六进制输出长度，避免先生成中间字符串。
    dst := make([]byte, hex.EncodedLen(len(src)))
    // Encode 直接覆盖 dst 的可写区域，并返回写入字节数。
    n := hex.Encode(dst, src)

    // 只使用 n 个已写入字节，便于后续把 dst 交给日志或协议层。
    fmt.Printf("encoded=%s bytes=%d\\n", dst[:n], n)
}

这段写法的重点不在于手算两倍，而在于把长度规则交给标准库 API。以后如果编码实现或调用方式变化，分配逻辑仍然和 Encode 的契约保持一致。对于小型一次性字段，EncodeToString 仍然更直观；这里的切片写法适合已有缓冲区或明确的热路径。

已有内容时，Encode 和 AppendEncode 不是一回事

如果目标切片前面已经写入了字段名、分隔符或版本号，就不要从 dst[0] 开始覆盖。此时可以让 AppendEncode 从当前切片末尾继续追加，它返回扩展后的切片，调用者不必自己计算追加位置。

package main

import (
    "encoding/hex"
    "fmt"
)

func main() {
    src := []byte{0x01, 0xaf, 0x20}
    dst := []byte("id=")

    // AppendEncode 从 dst 的当前长度开始追加，不会覆盖已有前缀。
    dst = hex.AppendEncode(dst, src)
    // 结果仍是普通字节切片，可继续追加分隔符或交给写入器。
    fmt.Println(string(dst))
}

整片覆盖和追加写入要先做架构选择：固定字段且已有最终长度时使用 Encode，有前缀或多个片段拼接时使用 AppendEncode。不要为了“复用”而强行把一个会不断增长的消息塞进固定长度切片。

容量足够不等于长度可写

下面这个区别在复用工作缓冲区时很关键：

package main

import (
    "encoding/hex"
    "fmt"
)

func main() {
    src := []byte{0xde, 0xad, 0xbe, 0xef}

    // cap 足够只代表底层数组有空间，Encode 仍需要 len(dst) 覆盖完整输出区。
    dst := make([]byte, 0, hex.EncodedLen(len(src)))
    // 先把切片长度扩展到可写范围，再交给 Encode 覆盖这些位置。
    dst = dst[:hex.EncodedLen(len(src))]
    n := hex.Encode(dst, src)

    // n 是本次写入长度；使用 dst[:n] 明确输出边界。
    fmt.Printf("%s (%d)\\n", dst[:n], n)
}

如果只是要追加，优先使用 AppendEncode，让它负责扩展切片。只有在你明确管理工作缓冲区生命周期时，才适合先把 len 调整到精确值再调用 Encode。这能减少“容量看起来够、函数却没有写满”的误判。

大输入和流式输入要换一种边界

EncodedLen(n) 的规则是 n*2，所以对来自不可信来源的超大长度，工程代码仍要先确认乘法不会超出可分配范围。普通日志字段或摘要通常可以固定上限；文件和网络流则不应该为了计算总长度而先把全部输入装进内存。

package main

import (
    "encoding/hex"
    "io"
)

func copyAsHex(dst io.Writer, src io.Reader) error {
    // NewEncoder 按块读取并写入目标 Writer，适合无法一次放进内存的输入。
    encoder := hex.NewEncoder(dst)
    // Copy 完成后把错误返回给调用方；编码器本身是 Writer，不需要额外 Close。
    _, err := io.Copy(encoder, src)
    return err
}

流式方案的取舍是：它不需要预先知道全部输入长度，但输出不再是一个可直接索引的单一切片。要不要使用它，取决于接收端是需要完整字段、可追加的消息缓冲，还是一个可以持续写入的 io.Writer。

工程落地时的选择清单

1. 能确定输入长度且要整片输出：用 make([]byte, hex.EncodedLen(len(src))) 加 Encode。
2. 目标已有内容：用 AppendEncode，不要自己把追加位置写死。
3. 只需要字符串：用 EncodeToString，优先可读性，不为不存在的热路径预优化。
4. 输入来自文件或网络流：用 NewEncoder，把内存上限和错误返回交给流式边界处理。
5. 复用工作缓冲区：同时检查 len、cap 和本次写入长度，避免切片边界错配。

常见疑问

为什么不是用 cap(dst) 作为 Encode 的长度？

cap 表示底层数组的最大可扩展空间，Encode 接收的是当前可写切片。要写入全部输出，应把 len(dst) 设置成 hex.EncodedLen(len(src))。

EncodedLen 返回的是字符数还是字节数？

它返回输出字节数。标准十六进制字符是单字节 ASCII 表示，因此在这个包的输出中也等于字符数量。

Encode 和 AppendEncode 可以互换吗？

不能完全互换。Encode 覆盖传入目标切片的输出区域；AppendEncode 保留已有内容并返回追加后的切片。

总结

hex.EncodedLen 的价值是把“输入字节数到输出缓冲区长度”的关系显式化：n 个输入字节对应 2n 个输出字节。固定长度字段用精确切片配合 Encode，已有前缀用 AppendEncode，超大输入改用 NewEncoder。最后牢记一条：容量只是空间上限，长度才是当前可写边界。