Rust / 系统课时
管理项目依赖
管理项目依赖
本课解决 Rust 项目如何准确声明第三方库的问题。你将直接编辑 Cargo.toml,掌握版本约束、Feature、可选依赖和开发依赖的写法,并通过 Cargo 命令验证依赖是否被正确解析。
学习目标
- 在
Cargo.toml中声明常用版本范围 - 为依赖启用 Feature,并配置可选依赖
- 区分运行依赖与仅测试、构建时使用的开发依赖
添加普通依赖
Cargo 使用 Cargo.toml 的 [dependencies] 区域管理编译和运行所需依赖。最简单的写法是填写版本字符串,也可以使用内联表同时设置版本与 Feature。
以下配置创建一个使用 serde 和 serde_json 的项目。serde 启用 derive Feature,以便通过派生宏实现序列化。
[package]
name = "dependency-demo"
version = "0.1.0"
edition = "2024"
[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"配套的 src/main.rs:
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}");
}运行命令:
cargo run预期输出:
{"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 时,下游项目会根据自己的依赖图重新解析版本。
可以使用以下命令查看当前解析结果:
cargo tree预期结果:
dependency-demo v0.1.0 (<PATH>)
├── serde v1.<VERSION>
└── serde_json v1.<VERSION><PATH> 和 <VERSION> 会随本地目录及仓库中的最新兼容版本变化,重点是确认依赖层级和主版本符合配置。
配置 Feature 与可选依赖
Feature 用于按需启用代码能力。依赖自身的 Feature 写在依赖项的 features 数组中;可选依赖则设置 optional = true,并通过当前包的 [features] 暴露开关。
[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 生效:
cargo tree --features json预期结果:
feature-demo v0.1.0 (<PATH>)
├── serde v1.<VERSION>
└── serde_json v1.<VERSION>未启用 json 时,这两个可选依赖不会进入依赖图。代码中还需使用 #[cfg(feature = "json")] 控制相关模块或函数,否则启用开关只会改变依赖解析,不会自动切换业务逻辑。
添加开发依赖
测试、示例和基准测试使用、但正式程序运行时不需要的库,应放入 [dev-dependencies]。这样可以避免把测试工具误当作生产依赖。
[package]
name = "dev-dependency-demo"
version = "0.1.0"
edition = "2024"
[dev-dependencies]
pretty_assertions = "1"片段示例:下面的测试代码依赖项目中已存在的 add 函数,适合放在对应模块内。
#[cfg(test)]
mod tests {
use pretty_assertions::assert_eq;
use super::add;
#[test]
fn adds_two_numbers() {
assert_eq!(add(2, 3), 5);
}
}运行测试:
cargo test预期结果:
test tests::adds_two_numbers ... ok测试汇总中的耗时、过滤数量和构建日志可能不同。核心验证标准是测试状态为 ok,且正式构建不会把 pretty_assertions 作为运行时依赖使用。
更新与检查依赖
cargo check 会解析并编译依赖,但通常比生成完整二进制更快,适合修改配置后的首次验证。cargo update 会在现有版本约束内更新 Cargo.lock,不会突破 Cargo.toml 声明的范围。
cargo check预期结果:
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、共享构建目录与依赖版本。