Go compress/flate.NewReaderDict 怎样用预置字典解压原始数据

我在做一段二进制协议的压缩层时，第一次把 compress/flate.NewReaderDict 接进来，最容易误判的地方不是 API 调用，而是输入边界：它接收的是原始 DEFLATE 数据，解压端还要拿到与压缩端完全一致的预置字典。只要字典内容、字节顺序或外层容器有一处对不上，错误通常会在真正读取数据时才暴露。

官方文档：https://pkg.go.dev/compress/flate#NewReaderDict

正确用法可以概括成一句话：压缩端用 flate.NewWriterDict 写出原始 DEFLATE，解压端用同一份 []byte 字典调用 flate.NewReaderDict，然后在 io.ReadAll 或循环 Read 时处理错误；如果输入是 zlib 或 gzip 容器，就应该换对应的 Reader。

先确认 NewReaderDict 处理的是什么数据

compress/flate 实现的是 DEFLATE 数据格式。它和 compress/zlib、compress/gzip 的关系，更像是“底层压缩编码”和“带容器的文件或传输格式”的关系。NewReaderDict 不会替你剥掉 zlib 头、gzip 头或校验尾；把带容器的字节直接交给它，通常会得到损坏输入一类的读取错误。

预置字典也不是解压端可选的提示。压缩端把字典中的常见片段当作匹配窗口的一部分，解压端必须能用同样的字节恢复引用。如果协议只传压缩结果、不约定字典版本，接收方即使拿到了完整字节流，也无法可靠地还原原文。

可以先用下面这张速查表确定入口：

用同一份字典完成压缩和解压

为了把问题缩小到字典本身，下面的示例故意使用原始 DEFLATE。字典里放的是业务数据中反复出现的片段；生产协议中还应把字典版本或选择规则作为协议的一部分，而不是依赖调用双方“刚好使用了同一段常量”。

package main

import (
	"bytes"
	"compress/flate"
	"fmt"
	"io"
	"log"
)

func main() {
	// 字典应包含输入中经常重复出现的字节片段。
	const dict = "user_id=|trace_id=|content-type=application/json|"
	const payload = "user_id=42|trace_id=abc-123|content-type=application/json|"

	var compressed bytes.Buffer
	// 压缩端和解压端必须约定同一份字典内容。
	zw, err := flate.NewWriterDict(&compressed, flate.DefaultCompression, []byte(dict))
	if err != nil {
		log.Fatal(err)
	}
	if _, err := io.WriteString(zw, payload); err != nil {
		// 写入失败时也要尝试关闭压缩器，避免资源未收尾。
		_ = zw.Close()
		log.Fatal(err)
	}
	if err := zw.Close(); err != nil {
		log.Fatal(err)
	}

	// NewReaderDict 读取的是原始 DEFLATE，不是 zlib 或 gzip 容器。
	zr := flate.NewReaderDict(bytes.NewReader(compressed.Bytes()), []byte(dict))
	defer zr.Close()
	plain, err := io.ReadAll(zr)
	if err != nil {
		// 字典不匹配或压缩字节损坏，通常会在读取阶段暴露。
		log.Fatalf("解压失败: %v", err)
	}
	fmt.Println(string(plain))
}

这里有三个值得保留的细节：

• NewReaderDict 本身返回的是 Reader，不是“已经完成校验的结果”；真正消费数据的是后面的 Read。
• defer zr.Close() 只负责收尾，不能替代对 io.ReadAll 错误的处理。
• 字典的类型虽然是 []byte，但内容就是协议的一部分；多一个空格、换一个编码或改了片段顺序，都可能让两端不再匹配。

错误为什么要在 Read 阶段判断

我在排查这类问题时，通常先把“构造 Reader 成功”与“成功解压正文”拆开看。创建 Reader 只是把读取器和输入连接起来，字典是否能正确支持后续的反向引用，要等 Reader 真正消费压缩字节时才有机会判断。

package main

import (
	"bytes"
	"compress/flate"
	"errors"
	"fmt"
	"io"
)

func decode(raw []byte, dict []byte) ([]byte, error) {
	// 这里不预判字典是否匹配，把判断交给实际的 DEFLATE 读取过程。
	zr := flate.NewReaderDict(bytes.NewReader(raw), dict)
	defer zr.Close()

	plain, err := io.ReadAll(zr)
	if err != nil {
		var corrupt flate.CorruptInputError
		if errors.As(err, &corrupt) {
			return nil, fmt.Errorf("原始 DEFLATE 或字典不匹配: %w", err)
		}
		return nil, fmt.Errorf("读取压缩流失败: %w", err)
	}
	return plain, nil
}

flate.CorruptInputError 能帮助调用方把“输入不是可接受的原始 DEFLATE”单独归类，但它不一定能只靠错误值告诉你究竟是字典版本错了，还是传输过程中损坏了字节。因此工程上最好同时记录压缩算法、字典标识、原始长度和校验信息，避免把所有问题都归咎于字典。

三类现象怎么区分

尤其要注意“同一份字典”与“同一个切片变量”不是一回事。协议只需要双方得到相同的字节内容；但如果某一侧在读取期间修改了字典底层数组，问题就会变成数据竞争或不可预测的解压失败。字典应在初始化后视为只读。

落地时把字典和容器一起写进协议

如果压缩层用于网络消息，我会把选择信息放在消息元数据里，例如 codec=deflate、dictionary=v3，再由接收端根据版本取得只读字典。这样出现读取错误时，日志可以直接回答“用了哪种算法、哪份字典、收到多少字节”，而不必先猜测。

如果数据要落盘或跨语言交换，zlib/gzip 往往更容易被工具识别，这时不要为了复用 NewReaderDict 而强行剥离容器。只有协议双方明确采用原始 DEFLATE，并且能稳定分发字典时，NewReaderDict 才是清晰的选择。

最后可以按这份清单收尾：

1. 确认输入是原始 DEFLATE，而不是 zlib/gzip 容器。
2. 压缩端和解压端使用完全一致的字典字节。
3. 在读取阶段处理错误，不能只检查 Reader 是否创建成功。
4. 字典初始化后按只读数据管理，不在并发读取期间修改底层数组。
5. 为算法、字典版本、原始长度和消息完整性保留可诊断信息。

相关问题

NewReaderDict 能直接读取 gzip 文件吗？

不能把 gzip 文件整体直接交给它。gzip 有自己的头、数据段和尾部校验，应使用 compress/gzip.NewReader。

字典不匹配一定会立刻报错吗？

不一定。Reader 可能先成功创建，错误在后续读取压缩数据时才出现；调用方应检查每次 Read 或 io.ReadAll 的返回值。

字典越大压缩效果越好吗？

不应这样假设。字典应包含输入中高频且稳定的片段，过大的字典会增加协议管理和版本协调成本，实际收益要结合数据形态评估。