Cargo 工作区与项目管理：从单 crate 到多 crate 的工程化组织

Cargo 工作区与项目管理：从单 crate 到多 crate 的工程化组织

一、项目大了，单 crate 就像把所有代码塞进一个文件

我的第一个 Rust 项目是一个 CLI 工具，所有代码都在一个 crate 里。刚开始还好，main.rs + 几个模块，cargo build 几秒搞定。后来加了配置解析、网络请求、数据缓存、日志系统……编译时间从 3 秒涨到 40 秒，cargo test 要跑 2 分钟。最烦的是改一行代码，整个项目都要重新编译。

Cargo Workspace（工作区）是解决这个问题的标准方案：把项目拆分为多个 crate，共享一个 Cargo.lock，独立编译、独立测试。这篇文章记录我从单 crate 重构到工作区的完整过程和踩过的坑。

二、Cargo 工作区的架构与依赖关系

flowchart TB
    A[workspace 根目录] --> B[Cargo.toml<br/>工作区配置]
    A --> C[crate: cli<br/>命令行入口]
    A --> D[crate: core<br/>核心业务逻辑]
    A --> E[crate: net<br/>网络请求层]
    A --> F[crate: cache<br/>缓存层]
    A --> G[crate: common<br/>共享工具]

    C -->|依赖| D
    C -->|依赖| E
    D -->|依赖| G
    E -->|依赖| G
    F -->|依赖| G
    D -->|依赖| F

    subgraph 编译优化
        H[增量编译<br/>只重编修改的 crate]
        I[并行编译<br/>无依赖的 crate 同时编译]
        J[feature 隔离<br/>可选依赖不影响核心]
    end

    style A fill:#e3f2fd
    style H fill:#e8f5e9
    style I fill:#fff3e0

Cargo 工作区的核心优势：增量编译（只重编修改的 crate）、并行编译（无依赖的 crate 同时编译）、依赖统一管理（共享 Cargo.lock）。依赖方向应该是单向的：cli → core → common，避免循环依赖。

三、代码实现与分析

3.1 工作区配置

# 根目录 Cargo.toml — 工作区配置
[workspace]
resolver = "2"
members = [
    "crates/cli",
    "crates/core",
    "crates/net",
    "crates/cache",
    "crates/common",
]

# 工作区级别的依赖版本统一管理
[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }
anyhow = "1"
thiserror = "1"
tracing = "0.1"
tracing-subscriber = "0.3"
reqwest = { version = "0.12", features = ["json"] }

# 工作区级别的 profile 配置
[workspace.profile.dev]
opt-level = 0

[workspace.profile.release]
opt-level = 3
lto = true
codegen-units = 1
strip = true

# crates/cli/Cargo.toml
[package]
name = "my-app-cli"
version = "0.1.0"
edition = "2021"

[dependencies]
my-app-core = { path = "../core" }
my-app-net = { path = "../net" }
clap = { version = "4", features = ["derive"] }
tokio = { workspace = true }
anyhow = { workspace = true }
tracing = { workspace = true }
tracing-subscriber = { workspace = true }

# crates/core/Cargo.toml
[package]
name = "my-app-core"
version = "0.1.0"
edition = "2021"

[dependencies]
my-app-cache = { path = "../cache" }
my-app-common = { path = "../common" }
serde = { workspace = true }
thiserror = { workspace = true }

# crates/common/Cargo.toml
[package]
name = "my-app-common"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { workspace = true }
serde_json = { workspace = true }

3.2 crate 内部组织

// crates/cli/src/main.rs — CLI 入口
use clap::Parser;
use my_app_core::Processor;
use my_app_common::config::AppConfig;

#[derive(Parser)]
#[command(name = "my-app", about = "示例应用")]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

#[derive(clap::Subcommand)]
enum Commands {
    /// 运行处理任务
    Run {
        #[arg(short, long, default_value = "config.toml")]
        config: String,
    },
    /// 查看状态
    Status,
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    tracing_subscriber::init();

    let cli = Cli::parse();

    match cli.command {
        Commands::Run { config } => {
            let app_config = AppConfig::from_file(&config)?;
            let processor = Processor::new(app_config);
            processor.run().await?;
        }
        Commands::Status => {
            println!("运行中");
        }
    }

    Ok(())
}

// crates/core/src/lib.rs — 核心业务逻辑
pub mod processor;
pub mod error;

pub use processor::Processor;
pub use error::CoreError;

// crates/core/src/processor.rs
use my_app_cache::Cache;
use my_app_common::config::AppConfig;

pub struct Processor {
    config: AppConfig,
    cache: Cache,
}

impl Processor {
    pub fn new(config: AppConfig) -> Self {
        let cache = Cache::new(config.cache_ttl);
        Self { config, cache }
    }

    pub async fn run(&self) -> Result<(), crate::CoreError> {
        // 核心业务逻辑
        Ok(())
    }
}

// crates/common/src/lib.rs — 共享工具
pub mod config;
pub mod types;

// crates/common/src/config.rs
use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct AppConfig {
    pub cache_ttl: u64,
    pub max_retries: u32,
}

impl AppConfig {
    pub fn from_file(path: &str) -> anyhow::Result<Self> {
        let content = std::fs::read_to_string(path)?;
        let config: AppConfig = toml::from_str(&content)?;
        Ok(config)
    }
}

// crates/cache/src/lib.rs — 缓存层
pub struct Cache {
    ttl: u64,
}

impl Cache {
    pub fn new(ttl: u64) -> Self {
        Self { ttl }
    }
}

// crates/net/src/lib.rs — 网络层
pub struct HttpClient {
    client: reqwest::Client,
}

impl HttpClient {
    pub fn new() -> Self {
        Self {
            client: reqwest::Client::new(),
        }
    }
}

3.3 工作区常用命令

# 构建整个工作区
cargo build

# 只构建某个 crate
cargo build -p my-app-cli

# 运行 CLI
cargo run -p my-app-cli -- run --config dev.toml

# 运行所有测试
cargo test

# 只运行某个 crate 的测试
cargo test -p my-app-core

# 运行特定测试
cargo test -p my-app-core -- processor::test

# 检查代码质量
cargo clippy --workspace

# 格式化代码
cargo fmt --all

# 查看依赖树
cargo tree -p my-app-cli

# 查看编译时间（需要 cargo-install cargo-nextest）
cargo nextest run --workspace

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

四、工作区管理的边界与权衡

crate 拆分的粒度：太粗（单 crate）失去增量编译优势，太细（每个模块一个 crate）增加维护成本。建议按"独立可测试"的原则拆分：如果一个模块有独立的测试套件且不经常与核心逻辑一起修改，就拆为独立 crate。一般 3-7 个 crate 是合理的范围。

循环依赖的检测与解决：如果 core 依赖 cache，cache 又依赖 core，就形成循环依赖，Cargo 会报错。解决方案：提取公共部分到 common crate，让两者都依赖 common。或者用 trait 抽象解耦——cache 定义 trait，core 实现 trait，通过依赖注入连接。

feature 的传播问题：工作区中，一个 crate 的 feature 可能影响依赖它的其他 crate。例如 core 开启 net 的 tls feature，所有依赖 core 的 crate 都会带上 tls。建议用 workspace-level feature 统一管理，避免 feature 意外传播。

版本发布策略：工作区中的 crate 通常一起发布，但也可以独立发布到 crates.io。独立发布时，crate 之间的版本依赖需要手动维护。建议在 CI 中用 cargo publish --dry-run 验证发布配置。

五、总结

Cargo 工作区是 Rust 项目工程化的基础：多 crate 组织实现增量编译和并行编译，workspace dependencies 统一管理依赖版本。本文的关键实践为：按"独立可测试"原则拆分 crate、依赖方向保持单向避免循环、用 workspace.dependencies 统一版本、用 cargo clippy --workspace 和 cargo fmt --all 保证代码质量。从单 crate 到工作区的重构，是项目从"能跑"到"好维护"的关键一步。