huffzip

README

HuffZip

基于哈夫曼树（Huffman Tree）的文件压缩/解压工具。纯 Go 实现，零外部依赖。

支持命令行和 Web 界面（htmx + Go html/template）两种使用方式。

原理

哈夫曼编码是一种无损数据压缩算法：

1. 统计频率 — 扫描输入数据，统计每个字节出现的次数
2. 构建哈夫曼树 — 频率低的字符在树的深层（编码长），频率高的在浅层（编码短）
3. 生成编码表 — 遍历树为每个字符生成变长二进制编码（前缀码，无歧义）
4. 按位压缩 — 将原始数据替换为对应的变长编码，按位打包为字节

解压时，从压缩文件头恢复频率表 → 重建相同的哈夫曼树 → 按位遍历树还原原始数据。

安装

go build -o huffzip.exe .

用法

命令行

# 压缩文件
.\huffzip.exe compress input.txt output.hfz

# 解压文件
.\huffzip.exe decompress output.hfz restored.txt

# 管道模式（- 表示 stdin/stdout）
echo "hello world" | .\huffzip.exe compress - out.hfz
.\huffzip.exe decompress out.hfz -

Web 界面

# 启动 Web 服务器（默认 :8080）
.\huffzip.exe web

# 指定端口
.\huffzip.exe web --addr :3000

启动后浏览器访问 http://localhost:8080 ，支持拖拽上传文件进行压缩/解压。

压缩文件格式（.hfz）

字段	类型	说明
Magic	[4]byte	"HFZP" 魔数
Version	uint8	格式版本 1
PaddingBits	uint8	最后一字节填充位数 (0-7)
FreqCount	uint16 BE	频率表条目数
FreqTable	[]entry	每条: byte(1) + uint32(4)
DataLen	uint32 BE	压缩数据字节数
Data	[]byte	压缩后的比特流

项目结构

huffzip/
├── main.go              # CLI + Web 入口
├── huffman/
│   ├── tree.go          # 哈夫曼树核心算法
│   └── tree_test.go     # 单元测试
├── codec/
│   ├── format.go        # 压缩文件格式读写
│   ├── encoder.go       # 编码器（压缩）
│   ├── decoder.go       # 解码器（解压）
│   └── codec_test.go    # 集成测试
└── web/
    ├── server.go        # HTTP 服务器、路由
    ├── handler.go       # 请求处理器
    ├── store.go         # 临时文件存储
    └── template/        # htmx 模板片段
        ├── layout.htmx  # 页面布局
        ├── home.htmx    # 首页
        ├── _compress.htmx   # 压缩结果
        ├── _decompress.htmx # 解压结果
        └── _error.htmx      # 错误提示

测试

go test ./... -v

注意事项

• 哈夫曼编码对短文本可能出现"膨胀"（压缩后更大），因为频率表头部有固定开销
• 对重复率高的大文件效果最佳
• 纯教学/练习用途，生产环境请使用 gzip/zstd 等成熟方案