3.5 使用第三方库（Cargo）

在 Rust 生态系统中，Cargo 不仅仅是包管理器，更是项目的“瑞士军刀”。它极大地简化了第三方库（在 Rust 中称为“crate”）的发现、下载、编译和集成过程。本节将详细介绍如何使用 Cargo 来管理和使用这些强大的外部代码库，从而避免重复造轮子，并利用社区的力量加速开发。

3.5.1 什么是 crate？

在 Rust 中，一个 crate 可以是一个库（library crate）或一个可执行程序（binary crate）。当你使用第三方库时，通常指的是一个库 crate。这些 crate 托管在 crates.io（Rust 的官方包注册中心）上，你也可以使用 Git 仓库或本地路径作为依赖源。

3.5.2 在项目中添加依赖

使用第三方库的核心步骤是在项目的 Cargo.toml 文件中声明依赖。Cargo 提供了两种主要方式：手动编辑和命令行添加。

方式一：手动编辑 Cargo.toml

打开项目根目录下的 Cargo.toml 文件，在 [dependencies] 部分添加 crate 名称和版本号。

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

[dependencies]
serde = "1.0"          # 一个流行的序列化/反序列化库
rand = "0.8"           # 一个随机数生成库
reqwest = { version = "0.11", features = ["json"] } # 一个 HTTP 客户端库，并启用 json 特性

版本号格式：

  • "1.0"：表示兼容 >=1.0.0 且 <2.0.0 的任何版本（语义化版本兼容）。
  • "=1.2.3"：只允许精确的 1.2.3 版本。
  • ">=1.0, <2.0"：指定版本范围。
  • "*"：使用最新版本（不推荐，可能导致构建不一致）。

方式二：使用 cargo add 命令（推荐）

这是最便捷的方式，Cargo 会自动更新 Cargo.toml 并下载依赖。

# 添加 serde 库
cargo add serde

# 添加特定版本
cargo add rand@0.8.5

# 添加并启用特定 features
cargo add reqwest --features json

# 从 git 仓库添加
cargo add my_crate --git https://github.com/user/my_crate.git

3.5.3 使用依赖库

一旦在 Cargo.toml 中声明了依赖，你就可以在 Rust 代码中使用 use 关键字来引入它们。

示例：使用 rand 库生成随机数

首先，确保 Cargo.toml 中有 rand 依赖。

[dependencies]
rand = "0.8"

然后，在 src/main.rs 中编写代码：

// 引入 rand crate 中的 Rng trait
use rand::Rng;

fn main() {
    // 创建一个随机数生成器
    let mut rng = rand::thread_rng();

    // 生成一个 1 到 100 之间的随机整数
    let random_number: u32 = rng.gen_range(1..=100);
    println!("生成的随机数是: {}", random_number);

    // 生成一个随机布尔值
    let random_bool: bool = rng.gen();
    println!("随机布尔值: {}", random_bool);
}

示例：使用 serde 和 serde_json 进行 JSON 序列化

首先，添加依赖并启用 derive 特性。

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

然后，使用派生宏和序列化函数：

use serde::{Serialize, Deserialize};

// 使用派生宏自动实现 Serialize 和 Deserialize trait
#[derive(Serialize, Deserialize, Debug)]
struct User {
    name: String,
    age: u8,
    email: String,
}

fn main() {
    let user = User {
        name: String::from("Alice"),
        age: 30,
        email: String::from("alice@example.com"),
    };

    // 将结构体序列化为 JSON 字符串
    let json_string = serde_json::to_string(&user).unwrap();
    println!("序列化后的 JSON: {}", json_string);

    // 将 JSON 字符串反序列化为结构体
    let deserialized_user: User = serde_json::from_str(&json_string).unwrap();
    println!("反序列化后的用户: {:?}", deserialized_user);
}

3.5.4 更新与移除依赖

  • 更新依赖：运行 cargo update 命令。Cargo 会忽略 Cargo.lock 文件，根据 Cargo.toml 中的版本约束，尝试将所有依赖更新到符合约束的最新版本。随后，它会更新 Cargo.lock 文件以锁定这些新版本。

  • 移除依赖：有两种方式。

    • 手动删除：从 Cargo.toml 的 [dependencies] 部分中移除对应的行。
    • 使用命令：cargo rm <crate_name>。例如：cargo rm rand。

3.5.5 理解 Cargo.lock 文件

Cargo.lock 文件是自动生成的，它记录了项目所有依赖的精确版本号。它的作用是确保构建的可复现性。无论你在哪台机器上、何时构建项目，只要 Cargo.lock 文件存在，Cargo 都会使用其中记录的精确版本，从而避免因依赖版本意外升级而导致的构建失败或行为变化。

  • 对于可执行程序：始终将 Cargo.lock 提交到版本控制系统中（例如 Git）。
  • 对于库 crate：通常不建议将 Cargo.lock 提交到版本控制中，因为库的使用者应该根据他们自己的 Cargo.lock 来决定依赖版本。

3.5.6 探索与查找第三方库

  • crates.io：访问 https://crates.io，这是 Rust 官方的包注册中心。你可以搜索、浏览、查看 crate 的文档、依赖、版本历史和下载量。
  • Lib.rs：一个非官方的、社区维护的 crate 索引网站，提供更友好的分类和评价系统。
  • Awesome Rust：一个 GitHub 仓库，收集了各个领域最优秀的 Rust 库和资源列表。

3.5.7 使用 Git 仓库或本地路径作为依赖

除了 crates.io，Cargo 还支持从 Git 仓库或本地文件系统引用依赖。

从 Git 仓库添加：

[dependencies]
my_crate = { git = "https://github.com/user/my_crate.git", branch = "main" }
# 也可以指定 tag 或 rev (commit hash)
# my_crate = { git = "https://github.com/user/my_crate.git", tag = "v1.0.0" }

从本地路径添加（用于开发或调试）：

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

这种方式非常适合在开发自己的库时，在另一个项目中进行集成测试。

3.5.8 依赖特性（Features）

许多 crate 提供了可选的特性（features），允许你按需启用或禁用某些功能，以减少编译时间和最终二进制文件的大小。

在 Cargo.toml 中启用特性：

[dependencies]
serde = { version = "1.0", features = ["derive"] }  # 启用 derive 宏支持
reqwest = { version = "0.11", features = ["json", "socks"] } # 启用 JSON 和 SOCKS 代理支持

你也可以在代码中通过 #[cfg(feature = "my_feature")] 条件编译来使用这些特性。

3.5.9 总结

Cargo 的依赖管理功能是 Rust 语言生产力的核心。通过简单地声明依赖，你就可以轻松集成成千上万个高质量的第三方库。掌握 cargo add、cargo update、cargo rm 等命令，理解 Cargo.lock 的作用，并能够灵活使用 Git 和本地路径依赖，将使你的 Rust 开发之旅更加高效和顺畅。

Last Updated::