Go zlib 怎样使用预置字典压缩短消息

短消息如果每次都携带相同的字段名、协议前缀或资源路径，单独使用 zlib 往往会先付出格式和校验开销，压缩收益不一定明显。这个场景可以把双方都知道的重复片段提前放进预置字典，再让压缩器引用它们。

Go 的做法是：发送端用 zlib.NewWriterLevelDict 创建 Writer，接收端用 zlib.NewReaderDict 创建 Reader，并且两端使用内容完全相同的字典。字典不会自动附在压缩流中；如果两边字典不匹配，解压端应把 zlib.ErrDictionary 当作协议配置错误处理。

官方文档：https://pkg.go.dev/compress/zlib

为什么短消息需要预置字典

预置字典适合“消息短、结构稳定、重复片段明显”的协议。例如每条消息都带有 GET /api/、Host:、固定 JSON 字段或相同的事件前缀。字典的价值不是存放完整样本，而是提供压缩器可以复用的字节片段。

这是一种有前置约束的压缩模式：压缩端和解压端必须事先约定字典版本。它适合固定协议和受控服务之间的通信，不适合把任意用户文本直接交给一份猜测出来的字典。

用 NewWriterLevelDict 压缩一条短消息

下面的示例把常见的 HTTP 风格片段放进字典，再压缩一条包含这些片段的短消息。level 可以使用 zlib.DefaultCompression，也可以按 CPU 与体积的取舍选择其它合法级别。

package main

import (
	"bytes"
	"compress/zlib"
	"fmt"
	"io"
)

func compressMessage(message, dict []byte) ([]byte, error) {
	var compressed bytes.Buffer

	// 字典只放协议中稳定重复的片段，避免把偶然内容带进长期配置。
	writer, err := zlib.NewWriterLevelDict(&compressed, zlib.DefaultCompression, dict)
	if err != nil {
		return nil, fmt.Errorf("create zlib writer: %w", err)
	}

	// Write 可能只写入内部缓冲；Close 负责把尾部数据和校验信息刷出。
	if _, err := io.Copy(writer, bytes.NewReader(message)); err != nil {
		_ = writer.Close()
		return nil, fmt.Errorf("write message: %w", err)
	}
	if err := writer.Close(); err != nil {
		return nil, fmt.Errorf("close zlib writer: %w", err)
	}
	return compressed.Bytes(), nil
}

func main() {
	// 生产环境应把这份字典作为协议版本的一部分管理。
	dict := []byte("GET /api/ Host: example.com Content-Type: application/json")
	message := []byte("GET /api/orders Host: example.com Content-Type: application/json")

	compressed, err := compressMessage(message, dict)
	if err != nil {
		panic(err)
	}
	// 这里只展示压缩流长度；不要依赖具体压缩字节序列做测试断言。
	fmt.Println("compressed bytes:", len(compressed))
}

这里有两个容易漏掉的细节。第一，字典的内容在 Writer 关闭前不能修改，因为 Writer 仍可能引用它。第二，必须检查 Close 的错误；仅检查 Write 成功并不代表完整 zlib 流已经写入底层目标。

用 NewReaderDict 配对解压

接收端需要拿到同一份字典，再把压缩字节交给 NewReaderDict。Reader 也要显式关闭，尤其是在底层 Reader 连接或文件还要继续使用时。

func decompressMessage(compressed, dict []byte) ([]byte, error) {
	reader, err := zlib.NewReaderDict(bytes.NewReader(compressed), dict)
	if err != nil {
		// 字典不一致通常在创建 Reader 时暴露，向上层保留原始错误类型。
		return nil, fmt.Errorf("create zlib reader: %w", err)
	}
	defer reader.Close()

	decoded, err := io.ReadAll(reader)
	if err != nil {
		return nil, fmt.Errorf("read decompressed message: %w", err)
	}
	return decoded, nil
}

func roundTrip(message, dict []byte) ([]byte, error) {
	// 压缩和解压共享同一个字典，模拟协议双方使用同一版本配置。
	compressed, err := compressMessage(message, dict)
	if err != nil {
		return nil, err
	}
	decoded, err := decompressMessage(compressed, dict)
	if err != nil {
		return nil, err
	}
	return decoded, nil
}

NewReaderDict 在压缩数据没有引用字典时可以忽略传入字典；但如果压缩流声明了另一份字典，函数会返回 zlib.ErrDictionary。因此调用方不能只把所有解压错误都归为“数据损坏”，应保留这个分类给协议协商或配置回滚逻辑。

字典不一致时，先区分哪一种错误

实际服务中，字典不一致常常来自部署顺序或协议版本没有一起切换。可以用 errors.Is 判断错误链，也可以直接比较标准库定义的错误值。判断结果应进入可观测日志，但日志里不要打印字典原文。

func classifyDictionaryError(err error) string {
	// 通过 errors.Is 保留包装错误后的可判断性，不泄露字典内容。
	if errors.Is(err, zlib.ErrDictionary) {
		return "dictionary-mismatch"
	}
	if errors.Is(err, zlib.ErrChecksum) {
		return "checksum-failed"
	}
	return "other-zlib-error"
}

上面的函数需要额外导入 errors。如果服务采用字典版本号，建议把版本号放在协议元数据或路由配置中，再决定重试、切换兼容字典，还是拒绝消息。不要为了“让它解出来”而随机尝试多份字典，这会掩盖发送端和接收端的版本错误。

这个模式的收益和代价

预置字典的收益来自重复片段已经存在于压缩器的可用上下文中，所以短消息也可能获得更好的压缩比例。但它不是无条件优化：

• 字典需要通过配置、版本或协议约定分发，双方必须保持一致。
• 字典本身不由 zlib 压缩流自动携带，接收端缺少字典时不能凭流内容恢复。
• 字典内容应保持稳定；把一次请求的动态字段塞进字典，会增加维护成本，反而可能降低命中率。
• 消息已经足够长或重复片段很少时，普通 zlib.NewWriter 可能更简单，应该以业务数据做基准比较。

因此，判断清单可以收敛为：消息是否短且重复稳定？字典能否随协议版本管理？压缩与解压双方是否能共享同一字节序列？能否把 ErrDictionary 与校验错误区分处理？四个问题都能回答“是”，再采用这个模式。

常见问题

字典需要包含完整的历史消息吗？

不需要。它更适合放协议中反复出现的字节片段；完整样本会增加配置体积，也可能把不稳定内容带入字典。

只在压缩端传字典可以吗？

不行。接收端必须预先拥有同一份字典，或者通过更高层协议完成字典协商；zlib 流不会替你传输字典。

为什么一定要调用 Writer.Close？

Writer 可能缓冲输出，Close 会刷新未写出的数据并结束 zlib 流；只调用 Write 不能保证接收端拿到完整结果。