系统工具从原型到可发布：代码之外还要做哪些事

系统工具从原型到可发布：代码之外还要做哪些事

一、原型完成那一刻，只走了 40% 的路

然后发现事情才刚刚开始。

我最近发布的一个文件去重工具，代码本身写了 800 行，但为了让它变成一个"别人能用的产品"，额外做的事情加起来不比写代码少。这篇文章就复盘一下：从原型到可发布，代码之外还要做哪些事。

pie title "原型 vs 可发布：工作量的真实分布"
    "核心代码实现" : 35
    "文档与帮助信息" : 20
    "打包与分发" : 15
    "测试与边缘 case" : 15
    "CI/CD 配置" : 8
    "安全与性能优化" : 7

二、代码之外必须做的五件事

1. 文档：README 是产品的第一印象

不是那种"给开发者看的技术文档"，而是**"一个完全不了解你项目的人，5 分钟内能不能跑起来"**。

我验证文档质量的方法很简单：把链接发给一个不懂 Rust 的朋友，看他能不能在不需要我解释的情况下安装并使用我的工具。

# fdedup — 高性能文件去重工具

使用 xxHash 哈希算法检测并删除重复文件。Rust 编写，单文件可执行。

## 快速开始

### 安装

```bash
# 方式一：cargo install
cargo install fdedup

# 方式二：下载预编译二进制
# 前往 Releases 页面下载对应平台的二进制文件

基本用法

# 在当前目录扫描重复文件（不删除，仅列出）
fdedup scan .

# 扫描并交互式确认删除
fdedup scan --delete-interactive /path/to/dir

# 按文件大小快速预筛选（跳过明显不重复的）
fdedup scan --pre-filter /path/to/dir

常用选项

### 2. 命令行帮助：`--help` 是最后的文档

假设用户找不到 README，或者离线使用，他唯一的信息来源就是 `--help`。

我的原则：**把 `--help` 当成产品的"紧急使用手册"来写。**

```rust
use clap::{Parser, Subcommand};

/// 高性能文件去重工具
///
/// 使用 xxHash 哈希算法快速检测目录中的重复文件。
/// 支持多种输出格式，支持交互式删除确认。
///
/// 示例：
///   fdedup scan .                           # 扫描当前目录
///   fdedup scan --delete-interactive ~/Downloads  # 交互式去重
///   fdedup scan --hash sha256 --output json .     # 用 SHA-256 输出 JSON
#[derive(Parser)]
#[command(name = "fdedup")]
#[command(version, about, long_about = None)]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]
enum Commands {
    /// 扫描目录查找重复文件
    Scan {
        /// 要扫描的目录路径
        path: String,

        /// 交互式确认删除（每次删除前都会询问）
        #[arg(long)]
        delete_interactive: bool,

        /// 自动删除（不询问，请谨慎使用！）
        #[arg(long, conflicts_with = "delete_interactive")]
        auto_delete: bool,

        /// 哈希算法：xxhash（快）、sha256（安全）、blake3（平衡）
        #[arg(long, default_value = "xxhash")]
        hash: String,

        /// 输出格式：table（终端友好）、json、csv
        #[arg(long, default_value = "table")]
        output: String,

        /// 只处理大于此大小的文件（如 1MB、10KB）
        #[arg(long)]
        min_size: Option<String>,

        /// 排除匹配 glob 模式的文件（如 "*.tmp"）
        #[arg(long)]
        exclude: Vec<String>,
    },

    /// 显示版本信息
    Version,
}

3. 打包与分发：让用户在 30 秒内用上

Rust 最大的优势之一是静态编译。但"编译出二进制"只是第一步。

flowchart LR
    A["源码"] --> B["cargo build --release"]
    B --> C["交叉编译\nWindows / macOS / Linux\nx86_64 + ARM64"]
    C --> D["strip 裁剪\n减小文件体积"]
    D --> E["打包\ntar.gz / zip / msi"]
    E --> F["上传 GitHub Release"]
    F --> G["用户下载解压即用"]

关键命令：

# 1. 生产构建
cargo build --release

# 2. 裁剪符号表和调试信息（减小 40-60% 体积）
strip target/release/fdedup

# 3. 交叉编译（以 macOS 为例，编译 Linux 二进制）
# 先安装目标工具链
rustup target add x86_64-unknown-linux-musl
# 静态链接 musl，不依赖 glibc 版本
cargo build --release --target x86_64-unknown-linux-musl

4. 边缘场景处理：用户比你想象中更"有创造力"

我在测试中遇到的几个场景：

/// 边缘场景集合——实际用户反馈的真实 case
mod edge_cases {
    use super::*;

    /// 场景 1：空目录
    /// 用户执行 fdedup scan /tmp/empty_dir
    /// 期望：不报错，输出 "未找到重复文件"
    fn handle_empty_directory() { /* ... */ }

    /// 场景 2：超大文件
    /// 用户扫描一个 50GB 的虚拟机镜像文件
    /// 需要分块读取哈希，避免一次加载全部
    fn handle_large_file() { /* ... */ }

    /// 场景 3：符号链接/硬链接
    /// Unix 系统下，两个路径指向同一个 inode
    /// 应该识别为"同一个文件"而非"重复文件"
    fn handle_hardlinks() { /* ... */ }

    /// 场景 4：文件在扫描过程中被删除
    /// 用户可能在扫描过程中手动删除了文件
    /// 需要优雅处理，不能 panic
    fn handle_file_vanished() { /* ... */ }

    /// 场景 5：文件名含特殊字符
    /// 空格、引号、emoji、控制字符都需要正确处理
    fn handle_special_filenames() { /* ... */ }
}

5. CI/CD：自动化一切重复劳动

自学的朋友可能对 CI/CD 比较陌生，但它是"可发布"的门槛之一：

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'  # 推送 v1.0.0 之类的 tag 时触发

jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        include:
          - os: ubuntu-latest
            target: x86_64-unknown-linux-gnu
            artifact_name: fdedup-linux-amd64
          - os: macos-latest
            target: x86_64-apple-darwin
            artifact_name: fdedup-macos-amd64
          - os: windows-latest
            target: x86_64-pc-windows-msvc
            artifact_name: fdedup-windows-amd64.exe

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          target: ${{ matrix.target }}

      - name: Build Release
        run: cargo build --release --target ${{ matrix.target }}

      - name: Run Tests
        run: cargo test --release

      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.artifact_name }}
          path: target/${{ matrix.target }}/release/fdedup${{ matrix.os == 'windows-latest' && '.exe' || '' }}

  publish:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          files: artifacts/*
          generate_release_notes: true

三、优先级判断：什么先做、什么后做

flowchart TD
    A["核心功能完成"] --> B["基础错误处理"]
    B --> C["CLI 帮助信息"]
    C --> D["README 文档"]
    D --> E["打包脚本 + 第一个 Release"]
    E --> F{"有用户反馈？"}
    F -->|有| G["根据反馈调整优先级"]
    F -->|没有| H["边缘 case 处理"]
    H --> I["CI/CD 自动化"]
    I --> J["性能优化"]

先做的永远是"能让用户跑起来"的事：文档和打包。后做的是"让用户不踩坑"的事：边缘 case 和 CI/CD。

四、我的"发布检查清单"

每次发布前逐条核对：

• cargo test 全部通过
• cargo clippy 没有 warning
• --help 输出信息完整准确
• README 的"快速开始"部分能在干净系统上一键运行成功
• 跨平台二进制都编译成功（至少 Linux + macOS）
• 空输入、超大输入、乱码输入都做了处理
• 敏感信息（API key 等）没出现在代码或日志中
• CHANGELOG 写了本次变更

补充一条血的教训：我之前漏掉了 --help 里的退出码说明，用户 grep + --help 的结果当脚本用了，遇到错误时脚本没有正确中断，导致后续操作在脏数据上跑。现在我把退出码、日志级别都写在帮助里。

还有两条容易漏的：第一，Cargo.toml 里 license 字段跟实际代码目录里的 LICENSE 文件对不对得上——有人改了 LICENSE 但忘了同步 Cargo.toml，发布后被人追着问；第二，cargo package --list 看看实际打进的包里有没有临时文件、.env 或调试脚本，这些不该出现在分发包里。建议发布前跑一遍 cargo package 再进 CI。

五、总结

自学 Rust，最大的陷阱不是学不会语法，而是满足于"代码能跑"。

原型阶段代码只占 35%~40% 的工作量，剩下的 60% 是文档、打包、测试、边缘 case 和 CI/CD——这些才是把"一个程序"变成"一个产品"的关键。

我的建议：发布第一个版本时不要太追求完美。 核心功能能跑 + README 能让人用起来 + 错误信息说人话——就可以发 v0.1.0 了。后续根据反馈迭代，比闭门造车有效率得多。

共勉。

你发布过 Rust 工具吗？分享一下你的发布经验吧。