Go ascii85.Encode 怎样预留目标缓冲并截取有效结果

第一次用 Go 的 encoding/ascii85 做二进制文本化时，最容易写错的不是编码公式，而是目标缓冲区。ascii85.Encode 会把结果写入调用方提供的 dst，并返回实际写入的字节数。正确的组合是：用 ascii85.MaxEncodedLen(len(src)) 计算最大空间，让 dst 的长度达到这个值，再用 dst[:n] 截出有效结果。

官方地址：https://pkg.go.dev/encoding/ascii85#Encode

不要只写 make([]byte, 0, max)。这只增加了容量，len(dst) 仍然是 0；而 Encode 会按下标写入目标切片。一次完整切片编码的最小可靠写法是 dst := make([]byte, ascii85.MaxEncodedLen(len(src)))，随后只使用 dst[:n]。

目标缓冲区为什么要有“长度”

Go 切片同时有长度和容量。容量表示底层数组还能向后扩展，长度才表示当前可以通过下标访问的元素范围。ascii85.Encode 的实现会直接写入 dst[0] 到 dst[4] 等位置，因此调用方必须提供足够的切片长度；仅有容量并不能让下标写入合法。

package main

import (
	"encoding/ascii85"
	"fmt"
)

func main() {
	src := []byte("Go")
	max := ascii85.MaxEncodedLen(len(src))

	// 长度为 max，Encode 才能直接把编码结果写入 dst。
	dst := make([]byte, max)
	n := ascii85.Encode(dst, src)

	// 返回值表示本次真正写入的字节数，不能默认等于 len(dst)。
	fmt.Printf("max=%d written=%d encoded=%q\n", max, n, dst[:n])
}

反例是 dst := make([]byte, 0, max)。它看起来为结果预留了空间，但长度仍为 0，不能作为 Encode 的目标切片。若确实需要从零长度切片开始构造，就要先把它扩展成可写长度；对这个 API 来说，直接用 make([]byte, max) 更清楚。

用 MaxEncodedLen 一次预留足够空间

ascii85.MaxEncodedLen(n) 返回长度为 n 的源数据可能产生的最大编码长度。ASCII85 通常把 4 个源字节编码成 5 个结果字节，所以最大值按 4 字节分组向上取整后乘以 5。调用方不必自己拼接这个公式，直接使用标准库函数即可。

package main

import (
	"encoding/ascii85"
	"fmt"
)

func encodeOnce(src []byte) []byte {
	// MaxEncodedLen 同时覆盖完整分组和最后不足四字节的片段。
	dst := make([]byte, ascii85.MaxEncodedLen(len(src)))
	n := ascii85.Encode(dst, src)

	// 只返回有效区间，避免把预留但未写入的零字节传给下游。
	return dst[:n]
}

func main() {
	encoded := encodeOnce([]byte("hello, ascii85"))
	fmt.Printf("%q\n", encoded)
}

这里的返回值是一个重新切片后的视图，仍然引用原来的 dst 底层数组。如果需要在长时间持有结果时进一步控制内存，可以再复制一份精确长度的结果；如果只是立即写入文件、响应或下一个处理函数，直接使用 dst[:n] 通常更合适。

为什么结果长度可能小于最大长度

MaxEncodedLen 给的是上限，不是本次一定会写入的长度。Encode 返回实际写入量，所以目标缓冲区常常会比有效结果更长。尤其是源数据不是 4 的整数倍时，最后一个片段会使用短编码，低位输出不会全部保留。

package main

import (
	"encoding/ascii85"
	"fmt"
)

func show(src []byte) {
	max := ascii85.MaxEncodedLen(len(src))
	dst := make([]byte, max)
	n := ascii85.Encode(dst, src)

	// 用 len(encoded) 观察真实输出，不把 max 当成结果长度。
	encoded := dst[:n]
	fmt.Printf("src=%d max=%d written=%d result=%q\n",
		len(src), max, len(encoded), encoded)
}

func main() {
	show([]byte{1, 2, 3, 4})
	show([]byte{1, 2, 3})
	show([]byte{0, 0, 0, 0})
}

完整的 4 字节零块还可能使用 z 这种特殊缩写，因此实际写入长度可能明显小于按 5 字节估算的上限。下游要读取或写出的始终是 encoded，而不是整个 dst；否则会把未使用的零字节一并当成编码内容。

复用缓冲区时要保留返回长度

在循环中复用目标数组可以减少分配，但每一轮都必须重新计算当前输入的最大长度，并保存当前轮的 n。如果上一轮结果更长，下一轮不能继续沿用旧的完整范围。

package main

import (
	"encoding/ascii85"
	"fmt"
)

func main() {
	inputs := [][]byte{[]byte("long input"), []byte("short")}
	buffer := make([]byte, ascii85.MaxEncodedLen(len(inputs[0])))

	for _, src := range inputs {
		if len(buffer) 

如果并发 goroutine 会同时使用这块缓冲区，就不能把同一个 buffer 无保护地复用给多个任务。复用解决的是分配问题，不会自动解决数据所有权和同步问题；需要异步持有时，应在交接前复制有效区间。

什么时候改用 NewEncoder

Encode 适合已经拿到完整源切片、希望一次得到结果的场景。官方文档特别指出，ASCII85 按 4 字节块工作，直接对大型数据流的单个块调用 Encode 不适合，因为每次调用都可能把尾部片段当成最终片段处理。

当数据来自文件或网络流，且不希望一次性把全部内容放入内存时，应使用 ascii85.NewEncoder 包装一个 io.Writer，最后调用 Close 刷出尾部数据。本文标题对应的是一次完整切片的目标缓冲和有效长度，不把流式编码混进同一套 dst[:n] 逻辑。

最后记住这四个判断

• 看长度，不只看容量：Encode 要求 dst 有足够的可写长度，make([]byte, 0, max) 不是等价写法。
• 用标准库算上限：目标切片长度使用 ascii85.MaxEncodedLen(len(src))。
• 只消费有效范围：实际结果是 dst[:n]，n 由 Encode 返回。
• 区分完整切片和数据流：完整数据一次编码用 Encode，持续写入则考虑 NewEncoder 并正确关闭。

把这套规则记成一句话就够了：先按 MaxEncodedLen 创建有足够长度的目标切片，再让 Encode 告诉你写了多少，最后只把 dst[:n] 交给下游。

相关问题

• ascii85.Encode 为什么不能只给目标切片设置容量？
• MaxEncodedLen 返回的是实际长度还是最大长度？
• 复用 ASCII85 缓冲区时，上一轮的返回长度能不能继续使用？
• 大文件编码为什么更适合 NewEncoder？