# chop_zip

**Repository Path**: yannischen/chop_zip

## Basic Information

- **Project Name**: chop_zip
- **Description**: 将压缩文件进行分解并合并，支持mac,windows
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-20
- **Last Updated**: 2026-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# chop_zip

大压缩文件分拆与合并工具 —— 将超大 zip 文件按指定大小切分成多个小文件便于传输，在目的端使用同一程序无损还原。跨平台，零依赖，安装即用。

![platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20x64-blue)
![language](https://img.shields.io/badge/language-Go-00ADD8)
![status](https://img.shields.io/badge/status-开发中-orange)

## 为什么需要 chop_zip

传输大压缩文件时经常遇到：

- 即时通讯 / 邮件 / 网盘的**单文件大小限制**
- 网络不稳定，大文件一旦失败**整体重传**成本过高
- 分卷工具生成的包**必须依赖同一工具且格式专有**

chop_zip 将大 zip 切成指定大小的独立分块 + 一份清单（manifest），逐块传输后在目的端用同一程序合并，全程 SHA-256 校验，**逐字节无损还原**。

## 特性

- **无损还原**：合并结果与原文件 SHA-256 完全一致
- **全程校验**：每个分块独立记录 SHA-256，损坏/缺失/篡改可精确定位到具体分块
- **跨平台**：macOS（x64 / arm64）与 Windows x64 单二进制，无需安装任何运行时
- **大文件友好**：流式读写，内存占用恒定（默认 4 MiB），GB 级文件无压力
- **格式可扩展**：架构采用策略模式隔离压缩格式逻辑，首期支持 zip，后续可扩展 tar.gz / 7z 等（见架构文档 §5.2）
- **同一程序双向使用**：分拆端与合并端使用同一程序，无需其他工具

## 安装

### macOS（x64 / arm64）

```bash
# 1. 从 Release 页面下载对应架构的 tar.gz 并解压
tar -xzf chop_zip_<版本>_macOS_x64.tar.gz

# 2. 赋予执行权限并移动到 PATH
chmod +x chop_zip
sudo mv chop_zip /usr/local/bin/
```

> 首次运行若提示"无法验证开发者"，执行：
> `xattr -d com.apple.quarantine /usr/local/bin/chop_zip`

### Windows（x64）

1. 从 Release 页面下载 `chop_zip_<版本>_Windows_x64.zip` 并解压；
2. 将解压目录加入 `PATH`（系统设置 → 环境变量），或直接在解压目录使用。

验证安装：

```bash
chop_zip version
```

## 快速开始

### 分拆

```bash
# 将 a.zip 切成 100MiB 的分块
chop_zip split -s 100M a.zip
```

输出：

```
a.zip.chop/
├── manifest.json     # 清单：校验基准，合并必需
├── a.zip.001
├── a.zip.002
└── …
```

### 传输

将 `a.zip.chop/` 目录内的**所有文件**（含 `manifest.json`）逐个传输到目的端机器，放入同一目录。

### 校验（可选）

```bash
chop_zip verify a.zip.chop
```

### 合并（目的端）

```bash
chop_zip merge a.zip.chop
# 成功后得到 ./a.zip
```

### 更多用法

```bash
chop_zip split -s 4M -o ./chunks a.zip         # 4MiB 分块，输出到指定目录
chop_zip split -s 1G a.zip                     # 1GiB 分块
chop_zip merge -o ./restore a.zip.chop         # 还原到指定目录
chop_zip merge --delete-chunks a.zip.chop      # 成功后删除分块目录（需二次确认）
```

`--size` 支持 `K` / `M` / `G` 单位或纯字节数（最小 1M）。

#### 分块大小的自动修正规则

为保证顺序 IO 性能，**输入的分块大小会被自动向上修正为 4 MiB 的整数倍**，修正规则如下：

| 你输入的 `--size` | 实际执行的分块大小 | 说明 |
| --- | --- | --- |
| `4M` / `100M` / `952M` / `1G`（4 的整数倍） | 与输入**完全一致** | 推荐用法 |
| `950M`（非 4 的整数倍） | **952 MiB**（向上修正） | 950 ÷ 4 = 237.5 → 进位为 952，系统里会看到 952 MB |
| `500K`（低于最小值） | 报错退出 | 最小块大小为 1M |

- 修正发生时程序会打印提示：`chunk size aligned 950 MiB -> 952 MiB`（`-q` 静默模式下不显示）；
- 若需分块**不超过**某上限（如传输通道限制 950M），请向下改用 4 的倍数：`-s 948M`；
- **末块为余数**：总大小除不尽时最后一个分块必然小于声明值（如 11MiB 按 4MiB 切 → 4 + 4 + 3），属正常现象；
- 修正后的精确字节数记录在输出目录 `manifest.json` 的 `chunk.declared_size` 字段中，是权威核对依据。

> 单位为二进制：`1M = 1024 KiB = 1,048,576 字节`（不是十进制的 100 万）。

## 工作原理

1. **分拆**：检测格式（zip）→ 流式切割为编号分块，同时计算每块 SHA-256 → 生成清单；
2. **清单**：记录原文件名/大小/整体 SHA-256，以及每个分块的文件名/大小/SHA-256；同时输出冗余副本 `manifest.bak`，主清单在传输中丢失时可用它恢复合并；
3. **合并**：校验清单与全部分块 → 按序流式拼接 → 整体 SHA-256 终验 → zip 结构校验 → 还原完成。

任一分块损坏或缺失，程序会明确报出**分块编号 + 期望/实际校验值**，只需重新传输该块（此时进程退出码为 `2`，便于脚本判断重传）。

## 支持格式

| 格式 | 状态 |
| --- | --- |
| zip | ✅ 首期支持 |
| tar.gz / 7z | 🗓 计划中（架构已预留，见路线图） |

新增格式只需实现一个策略类并注册，核心代码零改动 —— 详见[架构设计文档](docs/architecture.md)。

## 软件架构

采用分层架构（CLI / 应用服务 / 领域核心 / 格式策略 / 基础设施），核心分块/合并逻辑与压缩格式解耦：

- **策略模式**：`ArchiveHandler` 接口隔离格式检测与校验逻辑，zip 为首个实现；
- **门面模式**：应用服务层编排全流程，为未来 GUI 复用做好准备；
- **流式处理**：恒定内存，支持 GB 级大文件。

完整设计见：[docs/architecture.md](docs/architecture.md)

## 语言

帮助信息与运行提示支持中文和英文，按以下优先级选择：

1. `--lang` 标志：如 `chop_zip --lang=en -h`（可选 `zh` / `en`）
2. `CHOPZIP_LANG` 环境变量
3. 客户端系统语言自动检测（Windows 读取用户默认界面语言，macOS/Linux 读取 `LANG` / `LC_ALL`）

默认输出中文：仅当检测到客户端为英文环境（如英文 Windows / `LANG=en_*`），或显式指定 `en` 时才输出英文。示例：

```bash
chop_zip --lang=zh split -s 100M backup.zip    # 强制中文
chop_zip --lang=en verify backup.zip.chop      # 强制英文
```

## 从源码构建

需要 Go 1.22+。**以下所有命令均在仓库根目录下执行**（即含 `go.mod` 文件的目录）。开跑前可先执行 `go test ./...` 确认环境正常。

### 各平台编译命令（照着做即可）

编译只需要 4 步，**你在哪个系统上，就复制对应系统那一节的命令，整段粘贴回车**：

**第 1 步：安装 Go**（如果还没装）

到 https://go.dev/dl/ （国内镜像 https://golang.google.cn/dl/ ）下载安装包，一路下一步。安装后打开终端输入 `go version`，能显示版本号即可。

**第 2 步：获取代码并进入根目录**

```bash
git clone https://gitee.com/yannischen/chop_zip.git
cd chop_zip
```

（也可以在 Gitee 页面下载 ZIP 压缩包解压，然后进入 `chop_zip` 目录）

**第 3 步：复制你所用系统的命令，整段粘贴执行**

**Windows x64** —— 打开 PowerShell（开始菜单搜索 "PowerShell"），进入代码目录后粘贴：

```powershell
cd d:\你的路径\chop_zip        # 进入代码根目录（含 go.mod 的目录）
go build -trimpath -ldflags "-s -w" -o chop_zip.exe ./cmd/chop_zip
```

**macOS（无论 Intel 还是 M 系列芯片都一样）** —— 打开"终端"，进入代码目录后粘贴：

```bash
cd ~/你的路径/chop_zip          # 进入代码根目录（含 go.mod 的目录）
go build -trimpath -ldflags "-s -w" -o chop_zip ./cmd/chop_zip
```

> 不需要设置任何环境变量：Go 会自动编译出"当前电脑能用"的版本（Intel Mac 出 x64 版、M 系列 Mac 出 arm64 版）。

**第 4 步：确认产物**

命令无报错即成功，编译出的文件就在当前目录：

| 系统 | 产物文件 | 验证命令 |
| --- | --- | --- |
| Windows | `chop_zip.exe` | `.\chop_zip.exe version` |
| macOS | `chop_zip` | `./chop_zip version` |

## 路线图

- [x] v0.1：zip 分拆/合并/校验 CLI（发布二进制请打 tag 后执行 goreleaser）
- [ ] v0.2：tar.gz / 7z 格式扩展；Homebrew / Scoop 分发
- [ ] v0.3：单块重传模式、并行校验
- [ ] v0.4：GUI 桌面客户端

## 参与贡献

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码
4. 新建 Pull Request

## 许可证

[MIT](LICENSE)