MK
摩柯社区 - 一个极简的技术知识社区
AI 面试

Rust使用Cargo管理项目依赖

2022-08-227.6k 阅读

Rust 与 Cargo 的关系

Rust 作为一种高效、安全且注重并发编程的编程语言，其生态系统的核心工具之一便是 Cargo。Cargo 不仅仅是一个包管理器，它更是 Rust 项目开发流程中的多面手，从项目初始化、依赖管理到构建、测试和发布，Cargo 都提供了全面且便捷的功能。

在 Rust 项目中，Cargo 负责处理项目的依赖关系，确保项目能够获取到所需的外部库（也称为 crate）及其特定版本。这种依赖管理方式对于大型项目以及涉及多个团队协作的项目至关重要，它能够保证项目在不同环境下的一致性和可重复性。

Cargo 的基本概念

项目结构

在深入依赖管理之前，了解典型的 Rust 项目结构是有必要的。一个标准的 Rust 项目，通过 cargo new 命令创建后，会有如下结构：

my_project/
├── Cargo.toml
└── src/
    └── main.rs
  • Cargo.toml：这是项目的配置文件，包含了项目的元数据（如项目名称、版本、作者等）以及依赖信息。
  • src/ 目录：存放项目的源代码，main.rs 是可执行项目的入口文件，对于库项目则可能是 lib.rs。

Crate

Crate 是 Rust 中的一个编译单元，可以是一个库或者一个可执行程序。当我们在项目中使用外部功能时，我们依赖的就是一个个的 crate。例如，serde 是一个广泛使用的用于序列化和反序列化的 crate，许多 Rust 项目会将其作为依赖引入。

配置项目依赖

在 Cargo.toml 中声明依赖

在 Cargo.toml 文件中声明项目依赖是使用 Cargo 管理依赖的主要方式。打开 Cargo.toml 文件，在 [dependencies] 部分添加依赖项。例如，如果我们想要在项目中使用 rand crate 来生成随机数，可以这样添加：

[dependencies]
rand = "0.8.5"

这里，rand 是 crate 的名称，0.8.5 是版本号。Cargo 使用语义化版本号（SemVer）来管理依赖，这意味着只要遵循 SemVer 规范，Cargo 可以自动处理依赖的兼容更新。

如果项目有多个依赖，可以依次罗列：

[dependencies]
reqwest = "0.11.10"
tokio = { version = "1.18.2", features = ["full"] }

在上述示例中，reqwest 是用于 HTTP 请求的 crate，而 tokio 是一个异步运行时库。对于 tokio，我们不仅指定了版本号，还启用了 full 特性，特性（features）允许我们根据项目需求启用或禁用 crate 中的某些功能。

依赖版本说明符

  1. 具体版本号：如 rand = "0.8.5"，这表示项目依赖 rand crate 的 0.8.5 版本，Cargo 将只会下载和使用这个确切版本。
  2. 语义化版本范围：
    • ^ 前缀：rand = "^0.8.5" 表示项目依赖 0.8.5 及以上但小于 0.9.0 的版本。这是因为在 SemVer 中，首位数字（0）表示不稳定版本，次位数字（8）的增加表示向后兼容的新功能添加，而第三位数字（5）的增加表示向后兼容的 bug 修复。因此，^ 前缀允许在不改变首位数字的情况下进行次位和第三位数字的更新。
    • ~ 前缀：rand = "~0.8.5" 表示项目依赖 0.8.5 及以上但小于 0.9.0 的版本，且只会接受第三位数字的更新。即只允许 0.8.5 到 0.8.x 的版本，这里 x 是大于 5 的数字。
  3. 通配符版本：rand = "0.8.*" 表示项目依赖 0.8 系列的最新版本，Cargo 会下载最新的 0.8.x 版本。

依赖管理操作

下载依赖

当在 Cargo.toml 文件中添加或修改依赖后，运行 cargo build 或 cargo update 命令，Cargo 会下载项目所需的依赖。

  • cargo build：该命令会编译项目，如果依赖尚未下载，它会先下载依赖，然后进行编译。例如，在一个新添加了 rand 依赖的项目中运行 cargo build，Cargo 会首先从 crates.io（Rust 的官方 crate 注册表）下载 rand crate 及其依赖（如果有），然后编译项目代码。
  • cargo update：此命令会更新项目的依赖到符合 Cargo.toml 中版本说明符的最新版本。它不会重新编译项目，只是更新 Cargo.lock 文件（后面会详细介绍 Cargo.lock）。例如，如果 rand crate 有了新的 0.8.x 版本，运行 cargo update 会更新 Cargo.lock 文件以指向新的版本，下次运行 cargo build 时就会使用新的版本。

查看依赖树

通过 cargo tree 命令，我们可以查看项目的依赖树结构。例如，对于一个依赖了 rand 和 reqwest 的项目，运行 cargo tree 会输出类似如下的结果：

my_project v0.1.0 (/path/to/my_project)
├── rand v0.8.5
└── reqwest v0.11.10
    ├── async-trait v0.1.52
    ├── bytes v0.5.9
    ├── futures-util v0.3.21
    ├── http v0.2.8
    ├── hyper v0.14.20
    ├── isahc v0.10.4
    ├── log v0.4.14
    ├── mime v0.3.16
    ├── openssl v0.10.39
    ├── percent-encoding v2.1.0
    ├── pin-project-lite v0.2.8
    ├── serde v1.0.137
    ├── tower v0.4.11
    ├── tower-http v0.3.4
    └── tracing v0.1.33

这个输出展示了项目直接依赖的 rand 和 reqwest，以及 reqwest 所依赖的众多间接依赖。这有助于我们了解项目的依赖全貌，特别是在处理依赖冲突或优化依赖时。

清理依赖

有时候，我们可能想要清理项目中未使用的依赖，或者重新下载所有依赖以确保其完整性。

  • cargo clean：该命令会删除项目的目标目录（通常是 target/ 目录），其中包含了编译生成的文件和下载的依赖缓存。这在项目出现编译问题或者想要重新构建整个项目时很有用。运行 cargo clean 后，再次运行 cargo build 会重新下载依赖并编译项目。
  • 删除未使用的依赖：手动从 Cargo.toml 文件中删除不再使用的依赖项声明，然后运行 cargo build。Cargo 会根据新的 Cargo.toml 文件重新调整依赖，不再下载或使用已删除的依赖。

Cargo.lock 文件

作用

Cargo.lock 文件是 Cargo 依赖管理的关键组成部分。它记录了项目确切的依赖版本信息，包括直接依赖和间接依赖。当项目第一次构建或依赖更新时，Cargo 会生成或更新 Cargo.lock 文件。

这个文件的主要作用是确保项目在不同环境下构建时使用相同版本的依赖。例如，在开发环境中构建项目时，Cargo.lock 文件记录了当时下载的 rand crate 的 0.8.5 版本。当项目部署到生产环境或分享给其他开发者时，只要 Cargo.lock 文件存在，运行 cargo build 就会下载并使用完全相同版本的 rand crate，避免了因依赖版本不一致导致的问题。

何时更新

  1. 手动更新：运行 cargo update 命令时，Cargo 会根据 Cargo.toml 中的版本说明符更新 Cargo.lock 文件，指向符合条件的最新版本依赖。例如，如果 Cargo.toml 中 rand 的版本说明符是 ^0.8.5，且有新的 0.8.x 版本发布，运行 cargo update 会更新 Cargo.lock 文件以指向新的版本。
  2. 自动更新：当运行 cargo add 或 cargo remove 命令添加或删除依赖时，Cargo 会自动更新 Cargo.lock 文件。例如，使用 cargo add serde 添加 serde 依赖后，Cargo.lock 文件会被更新，记录 serde 及其依赖的版本信息。

版本控制

Cargo.lock 文件应该被纳入版本控制系统（如 Git）。这保证了团队成员在克隆项目时，能够使用与项目最初构建时相同版本的依赖。如果不将 Cargo.lock 文件纳入版本控制，不同成员在构建项目时可能会因为依赖版本的微小差异而遇到不一致的问题，例如编译错误或运行时行为不一致。

本地依赖与自定义注册表

本地依赖

除了从 crates.io 下载依赖，我们还可以使用本地路径作为依赖。这在开发多个相互关联的 Rust 项目或者进行本地 crate 开发和测试时非常有用。

假设我们有一个本地的 my_local_crate 项目，其路径为 /path/to/my_local_crate，并且我们想在另一个项目中使用它作为依赖。在依赖项目的 Cargo.toml 文件中，可以这样声明：

[dependencies]
my_local_crate = { path = "/path/to/my_local_crate" }

这样，Cargo 会将本地的 my_local_crate 项目作为依赖，并且在构建时会优先使用本地项目的代码，而不是从 crates.io 下载。这使得我们可以在本地对 my_local_crate 进行修改和调试，同时在依赖项目中实时看到效果。

自定义注册表

虽然 crates.io 是 Rust 官方的 crate 注册表，但在某些情况下，我们可能需要使用自定义的 crate 注册表。例如，在企业内部开发中，为了保护知识产权或提高网络访问效率，企业可能会搭建自己的 crate 注册表。

要使用自定义注册表，首先需要配置 Cargo。在 ~/.cargo/config 文件（Windows 下为 %USERPROFILE%\.cargo\config）中添加如下配置：

[registries]
my_custom_registry = { index = "https://example.com/custom-index" }

这里，my_custom_registry 是自定义注册表的名称，index 指向自定义注册表的索引 URL。

然后，在项目的 Cargo.toml 文件中声明依赖时，可以指定使用自定义注册表：

[dependencies]
my_custom_crate = { version = "1.0.0", registry = "my_custom_registry" }

这样，Cargo 会从自定义注册表 my_custom_registry 下载 my_custom_crate 的 1.0.0 版本。

依赖特性与条件编译

依赖特性

如前文提到的，许多 crate 提供了特性（features），允许我们根据项目需求启用或禁用某些功能。例如，serde crate 有多个特性，如 derive 特性用于自动派生序列化和反序列化代码。

在 Cargo.toml 文件中声明依赖时，可以启用特性：

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

启用 derive 特性后，我们就可以在代码中使用 #[derive(Serialize, Deserialize)] 宏来自动生成序列化和反序列化代码。

条件编译

条件编译允许我们根据不同的条件（如目标平台、特定的编译标志等）包含或排除代码块。这与依赖管理相关，因为我们可能需要根据不同条件依赖不同的 crate 或者使用 crate 的不同特性。

例如，在跨平台项目中，我们可能需要根据目标平台使用不同的文件系统操作库。在 Cargo.toml 文件中声明依赖：

[dependencies]
# 适用于 Unix 系统
unixfs = { version = "0.1.0", optional = true }
# 适用于 Windows 系统
winfs = { version = "0.2.0", optional = true }

然后在代码中使用条件编译：

#[cfg(unix)]
fn read_file() {
    use unixfs::read_file;
    read_file("/path/to/file").unwrap();
}

#[cfg(windows)]
fn read_file() {
    use winfs::read_file;
    read_file("C:\\path\\to\\file").unwrap();
}

这样，当项目针对 Unix 平台编译时，会使用 unixfs crate 的功能，而针对 Windows 平台编译时，会使用 winfs crate 的功能。

解决依赖冲突

在复杂的项目中，依赖冲突是常见的问题。当不同的依赖需要同一个 crate 的不同版本时，就会发生依赖冲突。例如，crate A 依赖 rand v0.8.5，而 crate B 依赖 rand v0.8.4。

Cargo 会尝试自动解决依赖冲突，通常通过选择一个满足所有依赖的版本范围的版本。如果无法自动解决，Cargo 会在构建时输出错误信息。

解决依赖冲突的方法有：

  1. 更新依赖：尝试更新相关依赖，看是否有新版本能够解决冲突。例如，如果 crate A 有新版本可以兼容 rand v0.8.4，则可以更新 crate A。在 Cargo.toml 文件中修改 crate A 的版本说明符，然后运行 cargo update。
  2. 指定版本：如果更新依赖不可行，可以尝试在 Cargo.toml 文件中手动指定冲突 crate 的版本，使得所有依赖都能兼容。例如，强制所有依赖都使用 rand v0.8.5：
[dependencies]
rand = "0.8.5"
crate_a = { version = "1.0.0", dependencies = { rand = "0.8.5" } }
crate_b = { version = "2.0.0", dependencies = { rand = "0.8.5" } }

通过这种方式，明确指定了 crate A 和 crate B 都使用 rand v0.8.5，从而解决冲突。但这种方法需要谨慎使用，因为可能会导致某些依赖的功能无法正常工作，需要对相关依赖有深入了解。

依赖管理与项目发布

发布到 crates.io

当我们开发好一个 Rust crate 并准备发布到 crates.io 时，依赖管理同样重要。首先，确保 Cargo.toml 文件中的依赖声明准确无误，并且所有依赖都符合发布要求。

在发布之前，运行 cargo publish --dry-run 命令进行预发布检查。这个命令会模拟发布过程，但不会真正将 crate 发布到 crates.io。它会检查 Cargo.toml 文件的格式、依赖关系等是否正确。

如果预发布检查通过，运行 cargo publish 命令将 crate 发布到 crates.io。Cargo 会根据 Cargo.toml 和 Cargo.lock 文件确保发布的 crate 及其依赖的完整性和一致性。

管理发布版本的依赖

当发布的 crate 有新版本时，需要谨慎管理依赖的更新。如果更新了依赖的版本，可能会影响依赖该 crate 的其他项目。因此，在更新依赖版本时，要遵循 SemVer 规范，并进行充分的测试。

例如，如果对发布的 crate 中的某个依赖进行了次要版本的更新（如从 1.0.0 到 1.1.0），并且这个更新是向后兼容的，那么在 Cargo.toml 文件中更新依赖版本后，在发布新版本的 crate 时，应确保更新 crate 的版本号的次要数字（如从 0.1.0 到 0.2.0），以告知其他开发者该 crate 有了新的功能（可能由于依赖更新引入）。

高级依赖管理技巧

版本替换

在某些情况下，我们可能需要在项目中使用一个 crate 的特定版本，而不是遵循常规的版本说明符。例如，我们发现了某个 crate 的一个 bug 并在本地修复了它，希望在项目中使用修复后的版本。

可以通过 replace 指令在 Cargo.toml 文件中实现版本替换：

[replace]
old_crate = { version = "1.0.0", path = "/path/to/fixed_crate" }

这里，old_crate 是原 crate 的名称，version 是原 crate 的版本，path 指向本地修复后的 crate 路径。这样，Cargo 会在构建项目时使用本地修复后的 crate 替代原 old_crate 的 1.0.0 版本。

间接依赖控制

虽然我们通常直接声明项目的直接依赖，但有时候也需要对间接依赖进行控制。例如，crate A 依赖 crate B，而 crate B 又依赖 crate C。我们可能想要对 crate C 的版本或特性进行控制。

可以通过在 Cargo.toml 文件中使用 package 部分来实现：

[package]
name = "my_project"
version = "0.1.0"

[dependencies]
crate_a = "1.0.0"

[patch.crates-io]
crate_c = { version = "0.5.0", features = ["special_feature"] }

在上述示例中，通过 patch.crates-io 部分，我们对来自 crates.io 的 crate C 进行了版本和特性的控制，即使 crate A 和 crate B 没有直接声明对 crate C 的特定要求，项目也会使用我们指定版本和特性的 crate C。

结语

通过深入了解和掌握 Cargo 的依赖管理功能，Rust 开发者能够更加高效地构建和维护项目。从基本的依赖声明、版本管理到复杂的依赖冲突解决、自定义注册表使用，Cargo 提供了一套完整且强大的工具集。在实际项目开发中，合理运用这些功能可以确保项目的稳定性、可维护性和可扩展性，使 Rust 项目在不同环境下都能可靠运行。无论是小型的个人项目还是大型的企业级应用，熟练掌握 Cargo 的依赖管理技巧都是必不可少的。