系统级工具链开发与Cargo工作区管理：从单文件到多crate工程-CSDN博客

系统级工具链开发与Cargo工作区管理：从单文件到多crate工程

cover

一、工具链项目的演进困境：单crate的膨胀之痛

我最初用Rust写的工具都是单文件或者单crate——一个main.rs搞定一切。但当工具变复杂，问题就来了：CLI参数解析、核心逻辑、输出格式化、配置管理全混在一起，改一处怕牵连其他，测试也分不清边界。

更麻烦的是，有些工具需要共享代码——比如日志库、配置解析、通用数据结构。复制粘贴显然不行，但拆成独立仓库又增加管理成本。后来我学到Cargo Workspace，才发现Rust生态早就给好了答案。

本文记录我从单crate到多crate工作区的实践过程，包括项目拆分策略、依赖管理、版本发布等。

二、Cargo工作区架构

2.1 工作区结构

graph TB
    A[workspace root] --> B[crates/cli]
    A --> C[crates/core]
    A --> D[crates/config]
    A --> E[crates/output]
    A --> F[crates/common]
    B --> C
    B --> D
    B --> E
    C --> F
    D --> F
    E --> F

2.2 工作区配置

根目录的Cargo.toml定义工作区：

[workspace]
resolver = "2"
members = [
    "crates/cli",
    "crates/core",
    "crates/config",
    "crates/output",
    "crates/common",
]

[workspace.package]
version = "0.1.0"
edition = "2021"
license = "MIT"
repository = "https://github.com/example/toolchain"

[workspace.dependencies]
# 共享依赖，统一版本
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
anyhow = "1.0"
clap = { version = "4.4", features = ["derive"] }
tracing = "0.1"
tracing-subscriber = "0.3"
tokio = { version = "1", features = ["full"] }

# 内部crate依赖
common = { path = "crates/common" }
core = { path = "crates/core" }
config = { path = "crates/config" }
output = { path = "crates/output" }

子crate的Cargo.toml使用workspace继承：

[package]
name = "cli"
version.workspace = true
edition.workspace = true

[dependencies]
common.workspace = true
core.workspace = true
config.workspace = true
output.workspace = true
clap.workspace = true
anyhow.workspace = true
tokio.workspace = true

2.3 Crate拆分原则

// crates/common/src/lib.rs - 通用工具
pub mod error {
    use anyhow::Result;
    pub type AppResult<T> = Result<T>;
}

pub mod format {
    pub fn format_size(bytes: u64) -> String {
        const KB: u64 = 1024;
        const MB: u64 = KB * 1024;
        const GB: u64 = MB * 1024;

        match bytes {
            0..KB => format!("{} B", bytes),
            KB..MB => format!("{:.1} KB", bytes as f64 / KB as f64),
            MB..GB => format!("{:.1} MB", bytes as f64 / MB as f64),
            _ => format!("{:.1} GB", bytes as f64 / GB as f64),
        }
    }
}

// crates/core/src/lib.rs - 核心业务逻辑
pub mod scanner {
    use std::path::PathBuf;
    use common::error::AppResult;

    pub struct FileScanner {
        root: PathBuf,
        max_depth: usize,
    }

    impl FileScanner {
        pub fn new(root: PathBuf, max_depth: usize) -> Self {
            Self { root, max_depth }
        }

        pub fn scan(&self) -> AppResult<Vec<PathBuf>> {
            let mut results = Vec::new();
            self.scan_recursive(&self.root, 0, &mut results)?;
            Ok(results)
        }

        fn scan_recursive(
            &self,
            dir: &std::path::Path,
            depth: usize,
            results: &mut Vec<PathBuf>,
        ) -> AppResult<()> {
            if depth > self.max_depth {
                return Ok(());
            }
            for entry in std::fs::read_dir(dir)? {
                let entry = entry?;
                let path = entry.path();
                if path.is_dir() {
                    self.scan_recursive(&path, depth + 1, results)?;
                } else {
                    results.push(path);
                }
            }
            Ok(())
        }
    }
}

// crates/config/src/lib.rs - 配置管理
use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct AppConfig {
    pub scan: ScanConfig,
    pub output: OutputConfig,
}

#[derive(Debug, Deserialize)]
pub struct ScanConfig {
    pub max_depth: usize,
    pub include_hidden: bool,
    pub extensions: Vec<String>,
}

#[derive(Debug, Deserialize)]
pub struct OutputConfig {
    pub format: String,
    pub color: bool,
}

impl AppConfig {
    pub fn load(path: &std::path::Path) -> common::error::AppResult<Self> {
        let content = std::fs::read_to_string(path)?;
        let config: AppConfig = toml::from_str(&content)?;
        Ok(config)
    }
}

三、CLI入口与集成

3.1 CLI定义

// crates/cli/src/main.rs
use clap::Parser;
use common::error::AppResult;

#[derive(Parser)]
#[command(name = "ftool")]
#[command(about = "A file analysis toolchain")]
struct Cli {
    /// Root directory to scan
    #[arg(default_value = ".")]
    root: String,

    /// Maximum scan depth
    #[arg(short, long, default_value = "10")]
    depth: usize,

    /// Output format: text, json, csv
    #[arg(short, long, default_value = "text")]
    format: String,

    /// Include hidden files
    #[arg(long)]
    hidden: bool,
}

#[tokio::main]
async fn main() -> AppResult<()> {
    let cli = Cli::parse();

    // 加载配置
    let config = config::AppConfig::load(
        std::path::Path::new("ftool.toml")
    ).unwrap_or_else(|_| config::AppConfig::default_from_cli(&cli));

    // 执行扫描
    let scanner = core::scanner::FileScanner::new(
        cli.root.into(),
        config.scan.max_depth,
    );
    let files = scanner.scan()?;

    // 格式化输出
    let formatter = output::Formatter::new(&config.output);
    formatter.display(&files)?;

    Ok(())
}

3.2 工作区常用命令

# 构建整个工作区
cargo build

# 只构建CLI
cargo build -p cli

# 运行CLI
cargo run -p cli -- --depth 5 /path/to/scan

# 测试所有crate
cargo test --workspace

# 测试单个crate
cargo test -p core

# 检查所有crate（快速编译检查）
cargo check --workspace

# 发布构建
cargo build --release -p cli