Go compress/flate NewWriterDict 什么时候适合使用预置字典

我第一次把 flate.NewWriterDict 放进文本协议时，最先关心的是“能不能压得更小”，后来发现真正容易出问题的是另一件事：接收端是否拿到了完全相同的字典字节。因此，Go 的预置字典只适合一种比较明确的场景：数据里会反复出现稳定的字段名、模板片段或协议前缀，而且压缩端与解压端可以提前约定字典。

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

预置字典解决的不是“所有数据都压得更小”

DEFLATE 会在已经看到的内容中寻找重复片段。预置字典相当于在真正的数据到来前，先给压缩器一段双方都知道的历史内容。假设每条消息都重复出现 "user_id"、"created_at"、模板标签或固定协议前缀，字典就可以把这些高频片段放到压缩开始前的上下文里。

这里的关键是“稳定重复”，而不是“文本很多”。一段很长但每次都完全不同的内容，未必适合固定字典；一段较短但字段和模板高度重复的协议消息，反而值得评估。官方示例也强调，字典应包含预计会在实际数据流中出现的子串，而不是随便塞入一段样本文本。

最小实现：压缩端和解压端各自使用同一份字典

先看一个完整但刻意保持简单的示例。字典用 []byte 表示，压缩端创建 Writer 后要在结束时调用 Close，否则缓冲中的尾部数据可能还没有写入目标缓冲区；解压端则使用同样的字典调用 NewReaderDict。

package main

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

func main() {
	// 字典应放入会反复出现的字段名和模板片段，而不是一次性业务值。
	dict := []byte(`{"user_id":,"created_at":,"status":,"items":}`)
	data := []byte(`{"user_id":42,"created_at":"2026-11-10T15:00:00Z","status":"ready","items":[1,2,3]}`)

	var compressed bytes.Buffer
	// 使用默认压缩级别；错误通常来自非法 level 或底层 Writer。
	zw, err := flate.NewWriterDict(&compressed, flate.DefaultCompression, dict)
	if err != nil {
		log.Fatal(err)
	}
	if _, err := zw.Write(data); err != nil {
		log.Fatal(err)
	}
	// Close 负责把编码器内部的尾部数据写入 compressed。
	if err := zw.Close(); err != nil {
		log.Fatal(err)
	}

	// 解压端必须拿到与压缩端逐字节相同的字典。
	zr := flate.NewReaderDict(bytes.NewReader(compressed.Bytes()), dict)
	decoded, err := io.ReadAll(zr)
	if err != nil {
		log.Fatal(err)
	}
	// Reader 也要关闭，释放它持有的解码资源。
	if err := zr.Close(); err != nil {
		log.Fatal(err)
	}

	fmt.Printf("压缩后=%d 字节，解压后=%d 字节，内容一致=%t\n", compressed.Len(), len(decoded), bytes.Equal(data, decoded))
}

这个例子只演示 API 关系，并没有承诺固定压缩比例。压缩结果还会受到输入长度、压缩级别和实际重复片段影响。工程里更重要的检查点是：字典的字符编码、拼接顺序、版本号和发布方式都必须可追踪。

为什么字典必须是同一份字节，而不是“差不多的文本”

预置字典参与的是压缩流的历史窗口。解压端如果使用另一份字典，即使人眼看起来只少了一个字段或多了一个空格，也不再是同一个协议输入。压缩端的字典来自 UTF-8 文本，解压端却按另一种编码转换，或者双方按不同顺序拼接片段，都会破坏这个约定。

我会把字典当成协议的一部分管理，而不是普通配置。至少要让消息能够识别字典版本，或者让连接两端在建立协议时明确协商版本。字典升级也不应该覆盖旧版本的解释规则：仍在网络中的旧消息，必须能被对应版本的接收端处理。

type Dictionary struct {
	// Version 用于让消息头或连接协商识别字典版本。
	Version string
	// Bytes 必须由固定顺序、固定编码的片段构成。
	Bytes []byte
}

var dictionaryV1 = Dictionary{
	Version: "v1",
	Bytes: []byte(`{"user_id":,"created_at":,"status":}`),
}

func compressWithDictionary(input []byte, d Dictionary) ([]byte, error) {
	var out bytes.Buffer
	// 生产代码应把 d.Version 一起写入协议元数据，而不是只传压缩体。
	zw, err := flate.NewWriterDict(&out, flate.DefaultCompression, d.Bytes)
	if err != nil {
		return nil, err
	}
	if _, err := zw.Write(input); err != nil {
		_ = zw.Close() // 出错路径仍尽量释放 Writer。
		return nil, err
	}
	if err := zw.Close(); err != nil {
		return nil, err
	}
	return out.Bytes(), nil
}

是否把版本写进消息头、连接参数还是服务配置，取决于协议本身；但不能只把压缩体交给一个“猜字典”的接收端。字典不匹配时，错误表现可能是解码失败，也可能让问题延迟到后续数据校验，排查成本会明显高于普通压缩。

这三类输入更值得考虑预置字典

第一类是字段名高度稳定的 JSON 或 XML 消息，例如同一接口不断传递不同用户值，但字段集合、嵌套骨架和固定枚举重复出现。第二类是模板化响应，例如邮件模板、配置片段或协议帧，正文变化集中在少数占位符。第三类是双方长期连接的内部协议：连接建立时就可以约定字典，后续消息不需要每次携带它。

这些场景共同具备三个条件：字典内容可提前准备；数据重复片段的分布相对稳定；接收方拥有明确的同版本字典。满足得越多，预置字典越像一个可维护的协议优化，而不是一次性的压缩技巧。

这四种情况通常应保留普通 flate

如果输入是短消息，固定字典带来的收益很快被管理复杂度抵消。若每个租户、每个请求甚至每个版本都需要不同字典，缓存和协商成本也可能超过压缩收益。跨团队、跨语言或跨服务传输时，无法保证对方实现相同的字典规则，也不宜把预置字典作为默认协议。

还有一种常见误区：把一份“看起来代表业务数据”的大样本文本直接当字典。字典应该包含预计反复出现的片段，且要考虑大小、更新和兼容成本；样本中独有的用户值、时间戳或随机 ID 既不能稳定匹配，还会让字典变得难以复用。

上线前用这张清单做选择

最后再强调一次：NewWriterDict 不是“自动学习字典”的接口，也不会替你做字典版本治理。它更像是把双方已经知道的重复上下文交给 DEFLATE 使用。只要输入特征稳定、两端能共享同一份字节、维护成本可控，就值得做小范围对比；否则，先用普通 flate.NewWriter 保持协议简单。

常见问题

预置字典是否必须包含完整的历史消息？

不需要。它应优先包含预计会重复出现的子串，例如字段名、固定标签和协议前缀；把整段偶然样本塞进去通常不利于复用。

压缩端和解压端能不能使用内容相近的两份字典？

不能把“相近”当作兼容条件。双方应使用逐字节一致的字典，并且把编码、拼接顺序和版本一起纳入协议管理。

调用 NewWriterDict 后为什么一定要 Close？

Writer 可能还保留着尚未输出的编码状态。Close 用来完成收尾并把尾部数据写入目标 Writer；只调用 Write 而不 Close，压缩流可能不完整。

是否应该为所有接口默认启用预置字典？

不建议。先确认重复片段稳定、两端可以同步字典、版本治理成本可接受，再对真实数据做对比；短小或高度变化的输入通常保持普通 flate 更稳妥。