Rust / 系统课时

管理项目依赖

管理项目依赖

本课解决 Rust 项目如何准确声明第三方库的问题。你将直接编辑 Cargo.toml,掌握版本约束、Feature、可选依赖和开发依赖的写法,并通过 Cargo 命令验证依赖是否被正确解析。

学习目标

  • 在 Cargo.toml 中声明常用版本范围
  • 为依赖启用 Feature,并配置可选依赖
  • 区分运行依赖与仅测试、构建时使用的开发依赖

添加普通依赖

Cargo 使用 Cargo.toml 的 [dependencies] 区域管理编译和运行所需依赖。最简单的写法是填写版本字符串,也可以使用内联表同时设置版本与 Feature。

以下配置创建一个使用 serde 和 serde_json 的项目。serde 启用 derive Feature,以便通过派生宏实现序列化。

toml
[package]
name = "dependency-demo"
version = "0.1.0"
edition = "2024"

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"

配套的 src/main.rs:

rust
use serde::Serialize;

#[derive(Serialize)]
struct User {
    id: u32,
    name: String,
}

fn main() {
    let user = User {
        id: 1,
        name: String::from("Ada"),
    };

    let json = serde_json::to_string(&user).expect("serialize user");
    println!("{json}");
}

运行命令:

bash
cargo run

预期输出:

text
{"id":1,"name":"Ada"}

首次运行时 Cargo 会解析版本、下载源码并生成 Cargo.lock。实际下载日志和编译耗时会因环境不同而变化,但程序输出应与上面一致。

理解版本约束

写成 serde_json = "1" 时,Cargo 使用兼容版本规则,允许选择 1.x 中满足条件的版本,但不会自动升级到 2.0.0。更精确的约束还包括 1.0、=1.0.120、>=1, <2 等形式。

应用项目通常应提交 Cargo.lock,以固定已解析版本并提高构建可复现性。库项目也会生成锁文件,但发布到 crates.io 时,下游项目会根据自己的依赖图重新解析版本。

可以使用以下命令查看当前解析结果:

bash
cargo tree

预期结果:

text
dependency-demo v0.1.0 (<PATH>)
├── serde v1.<VERSION>
└── serde_json v1.<VERSION>

<PATH> 和 <VERSION> 会随本地目录及仓库中的最新兼容版本变化,重点是确认依赖层级和主版本符合配置。

配置 Feature 与可选依赖

Feature 用于按需启用代码能力。依赖自身的 Feature 写在依赖项的 features 数组中;可选依赖则设置 optional = true,并通过当前包的 [features] 暴露开关。

toml
[package]
name = "feature-demo"
version = "0.1.0"
edition = "2024"

[features]
default = []
json = ["dep:serde", "dep:serde_json"]

[dependencies]
serde = { version = "1", features = ["derive"], optional = true }
serde_json = { version = "1", optional = true }

这里的 dep:serde 明确表示启用名为 serde 的可选依赖。验证依赖是否随 Feature 生效:

bash
cargo tree --features json

预期结果:

text
feature-demo v0.1.0 (<PATH>)
├── serde v1.<VERSION>
└── serde_json v1.<VERSION>

未启用 json 时,这两个可选依赖不会进入依赖图。代码中还需使用 #[cfg(feature = "json")] 控制相关模块或函数,否则启用开关只会改变依赖解析,不会自动切换业务逻辑。

添加开发依赖

测试、示例和基准测试使用、但正式程序运行时不需要的库,应放入 [dev-dependencies]。这样可以避免把测试工具误当作生产依赖。

toml
[package]
name = "dev-dependency-demo"
version = "0.1.0"
edition = "2024"

[dev-dependencies]
pretty_assertions = "1"

片段示例:下面的测试代码依赖项目中已存在的 add 函数,适合放在对应模块内。

rust
#[cfg(test)]
mod tests {
    use pretty_assertions::assert_eq;

    use super::add;

    #[test]
    fn adds_two_numbers() {
        assert_eq!(add(2, 3), 5);
    }
}

运行测试:

bash
cargo test

预期结果:

text
test tests::adds_two_numbers ... ok

测试汇总中的耗时、过滤数量和构建日志可能不同。核心验证标准是测试状态为 ok,且正式构建不会把 pretty_assertions 作为运行时依赖使用。

更新与检查依赖

cargo check 会解析并编译依赖,但通常比生成完整二进制更快,适合修改配置后的首次验证。cargo update 会在现有版本约束内更新 Cargo.lock,不会突破 Cargo.toml 声明的范围。

bash
cargo check

预期结果:

text
Finished `dev` profile [unoptimized + debuginfo] target(s) in <TIME>

<TIME> 是动态值。若出现 Feature 不存在、版本无法选择或依赖冲突,应先检查依赖名、版本范围和 Feature 拼写,再用 cargo tree -e features 查看实际启用链路。

本课总结

  • [dependencies] 用于正常编译与运行,[dev-dependencies] 用于测试等开发场景
  • Feature 可以启用依赖能力,可选依赖需通过 optional = true 和 dep: 显式连接
  • Cargo.lock 记录解析结果,cargo tree 与 cargo check 可用于验证配置

下一课预告

下一课将继续学习 Cargo 项目组织,了解工作空间如何统一管理多个 crate、共享构建目录与依赖版本。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

管理项目依赖

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通