Cargo 工作区实战——Rust 多 Crate 项目的工程化管理与工具链搭建

Cargo 工作区实战——Rust 多 Crate 项目的工程化管理与工具链搭建

一、单体仓库的膨胀困境：当 Cargo.toml 变得不可维护

Rust 项目从小型工具成长为系统级应用时，代码组织面临一个关键决策：是继续在单个 crate 中堆叠模块，还是拆分为多个 crate？

单体 crate 的症状很典型：编译时间随代码量线性增长，修改一个模块需要重新编译整个项目；use 路径越来越长，模块间的依赖关系隐式且混乱；测试运行缓慢，因为即使只测一个小模块也要编译整个 crate；不同模块的发布节奏不同，但被强制绑定在同一个版本号下。

Cargo Workspace（工作区）是 Rust 官方的多 crate 管理方案。它允许多个 crate 共享一个 Cargo.lock 和 target/ 目录，既保持了依赖版本的一致性，又避免了重复编译。更重要的是，工作区强制 crate 之间通过显式的依赖关系交互，消除了隐式耦合。

二、Cargo Workspace 的底层机制：共享与隔离的平衡

2.1 工作区结构

一个 Cargo Workspace 由一个根 Cargo.toml 和多个成员 crate 组成。根配置定义工作区范围，成员 crate 保持各自的独立性。

flowchart TD
    subgraph Workspace["Cargo Workspace"]
        ROOT["根 Cargo.toml\n[workspace]\nmembers = [...]"]
        ROOT --> A["crates/core\n共享核心库"]
        ROOT --> B["crates/cli\n命令行入口"]
        ROOT --> C["crates/server\nHTTP 服务"]
        ROOT --> D["crates/agent\nAI Agent 逻辑"]
        ROOT --> E["crates/wasm\nWASM 插件"]
    end

    B -->|depends on| A
    C -->|depends on| A
    D -->|depends on| A
    E -->|depends on| A
    D -->|depends on| C

    subgraph 共享资源
        LOCK["Cargo.lock\n统一版本锁定"]
        TARGET["target/\n共享编译缓存"]
    end

    ROOT --> LOCK
    ROOT --> TARGET

关键机制：

• 共享 Cargo.lock：所有成员 crate 使用同一份依赖锁定文件，避免版本冲突
• 共享 target/：依赖的公共库只编译一次，所有成员共享编译缓存
• 独立 Cargo.toml：每个成员有自己的依赖声明和版本号，保持模块独立性

2.2 依赖传递与特性传播

工作区中的 crate 依赖遵循 Rust 的标准规则：依赖默认是私有的，不会传递给上层。如果 crate A 依赖 crate B，crate B 依赖 serde，crate A 不会自动获得 serde 的访问权限，除非 crate B 的 Cargo.toml 中将 serde 声明为公共依赖。

# crates/core/Cargo.toml
[dependencies]
serde = { version = "1.0", features = ["derive"] }
# 将 serde 暴露为公共依赖，依赖 core 的 crate 可以直接使用
serde_json = "1.0"

[features]
# 定义特性开关，允许下游 crate 按需启用功能
default = ["json"]
json = ["serde_json"]
full = ["json"]

特性（Feature）是控制编译条件的重要机制。通过特性开关，可以让同一个 crate 在不同场景下编译不同的代码路径。例如，WASM 目标不需要 tokio，可以通过特性条件排除。

2.3 虚拟清单与工作区继承

Rust 1.64 引入了工作区继承（Workspace Inheritance），允许成员 crate 从根配置继承公共属性，减少重复配置：

# 根 Cargo.toml
[workspace]
members = ["crates/*"]

[workspace.package]
version = "0.1.0"
edition = "2021"
license = "MIT"

[workspace.dependencies]
# 统一管理依赖版本，避免不同 crate 使用不同版本
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
anyhow = "1.0"

# crates/cli/Cargo.toml
[package]
name = "my-agent-cli"
version.workspace = true    # 继承工作区版本
edition.workspace = true    # 继承工作区 edition

[dependencies]
my-agent-core = { path = "../core" }
serde.workspace = true      # 继承工作区依赖版本
tokio.workspace = true

三、生产级工作区配置：一个 AI Agent 工具链项目

下面展示一个完整的 AI Agent 工具链项目的 Cargo Workspace 配置，包含核心库、CLI 入口、HTTP 服务和 WASM 插件四个 crate。

# 根 Cargo.toml —— 定义工作区范围和共享配置
[workspace]
resolver = "2"
members = [
    "crates/core",
    "crates/cli",
    "crates/server",
    "crates/agent",
    "crates/wasm-plugin",
]

# 共享包属性，避免每个 crate 重复声明
[workspace.package]
version = "0.2.0"
edition = "2021"
rust-version = "1.75"
license = "MIT"
repository = "https://github.com/example/agent-toolkit"

# 共享依赖版本，确保所有 crate 使用同一版本
[workspace.dependencies]
# 内部 crate 依赖
agent-core = { path = "crates/core" }
agent-server = { path = "crates/server" }
agent-logic = { path = "crates/agent" }

# 序列化
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

# 异步运行时
tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "time", "io-util"] }

# 错误处理
anyhow = "1.0"
thiserror = "1.0"

# 日志
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

# crates/core/Cargo.toml —— 核心库，无外部依赖偏好
[package]
name = "agent-core"
version.workspace = true
edition.workspace = true

[dependencies]
serde.workspace = true
serde_json.workspace = true
thiserror.workspace = true
tracing.workspace = true

[features]
default = []
# WASM 目标不需要 tokio，通过特性条件排除
wasm = []

# crates/wasm-plugin/Cargo.toml —— WASM 插件，特殊配置
[package]
name = "agent-wasm-plugin"
version.workspace = true
edition.workspace = true

[lib]
crate-type = ["cdylib"]  # WASM 输出需要 cdylib

[dependencies]
agent-core = { path = "../core", features = ["wasm"] }
wasm-bindgen = "0.2"
serde.workspace = true

# WASM 目标不依赖 tokio
[features]
default = []

核心库的模块组织：

// crates/core/src/lib.rs
pub mod config;      // 配置加载与解析
pub mod error;       // 统一错误类型
pub mod tools;       // 工具注册与执行
pub mod context;     // 执行上下文管理

// 重新导出核心类型，简化下游 crate 的导入路径
pub use error::AgentError;
pub use config::Config;
pub use tools::ToolRegistry;
pub use context::ExecutionContext;

// crates/core/src/error.rs
use thiserror::Error;

/// 统一错误类型，所有子 crate 共享
#[derive(Debug, Error)]
pub enum AgentError {
    #[error("配置错误: {0}")]
    Config(String),

    #[error("工具执行失败 [{tool}]: {message}")]
    ToolExecution { tool: String, message: String },

    #[error("LLM 调用失败: {0}")]
    LlmCall(String),

    #[error("超时: {0}")]
    Timeout(String),

    #[error(transparent)]
    Io(#[from] std::io::Error),
}

四、工作区的工程代价：复杂度、编译策略与发布协调

认知复杂度增加。 工作区引入了 crate 间的依赖关系管理，开发者需要理解哪些代码属于哪个 crate、依赖方向是否合理。循环依赖在 Rust 中是被禁止的——如果 crate A 依赖 crate B，B 就不能再依赖 A。这要求在拆分 crate 时仔细规划依赖方向，通常采用"核心库无外部依赖、业务 crate 依赖核心库"的分层策略。

编译策略选择。 cargo build 默认编译所有成员 crate，但开发时通常只需要编译当前修改的 crate。cargo build -p <crate> 可以只编译指定 crate 及其依赖，显著减少编译时间。CI 环境中可以根据修改的文件路径，只编译受影响的 crate。

版本发布协调。 多 crate 项目需要协调版本发布。如果 core 从 0.2.0 升级到 0.3.0 并引入了破坏性变更，所有依赖 core 的 crate 都需要同步更新。cargo release 工具可以自动化这个过程，但配置和使用有一定学习成本。

WASM 目标的特殊处理。 WASM 插件 crate 不能依赖 tokio（浏览器没有原生异步运行时），需要通过特性条件排除。这要求核心库在设计时就将平台相关代码隔离到特性开关后面，增加了代码组织的复杂度。

适用边界：

五、总结

Cargo Workspace 通过共享依赖锁定和编译缓存，解决了多 crate 项目的版本一致性和编译效率问题。工作区继承特性减少了重复配置，特性开关支持按平台条件编译。合理的 crate 拆分策略是：核心库无外部偏好、业务 crate 依赖核心库、平台相关代码通过特性隔离。

工作区的代价是增加了项目组织的复杂度——依赖方向规划、版本发布协调、WASM 目标的特殊处理都需要额外的工程投入。但对于超过 5000 行的项目，这些投入是值得的。

落地路线建议：

1. 从单 crate 开始，当模块数量超过 5 个时考虑拆分
2. 拆分时先提取核心库，再逐步拆出业务 crate
3. 使用 workspace.dependencies 统一管理依赖版本
4. 开发时用 cargo build -p <crate> 只编译当前 crate
5. CI 中根据修改路径选择性编译，减少构建时间