Rust 从入门到精通11-包和模块管理项目

当我们项目较小时，一个 main.rs 文件就能搞定所有。但是如果项目较大，功能较多时，就很难搞定了。我们需要对相关功能进行分组和划分不同功能的代码，这样编写和维护都会比较方便。

如果你是一个Java程序员，相信你一定用过这样几个东西。首先项目较大，依赖较多，我们通常会使用maven/gradle 等工具进行依赖管理，然后将各个功能划分到不同的 package 中，比如（controller/service/dao/domain/utils等等）。

那么rust 程序员该如何管理大型项目呢？

①、Cargo: Rust 的包管理工具，能够管理外部依赖以及进行项目的编译和测试 create；

②、package: Cargo 提供的功能，一个包会含有一个 Cargo.toml 文件，是提供一系列功能的一个或多个 create。

③、create: 表示项目，是 Rust 中的独立编译单元。每个 create 对应生成一个库或可执行文件（.lib/.dll/.so/.exe）。

④、模块（Modules）和 use： 允许你控制作用域和路径的私有性。

⑤、路径（path）：为 struct、function 或 module 等项命名的方式。

PS：其实这么多名词核心问题就是如何管理作用域，我们代码中的变量、方法，开发者如何调用？又或者能够调用哪些？编译器如何去找？

1、Cargo

Cargo 是Rust 的包管理工具，并不是一个编译器。

Rust 的编译器是 rustc。

我们使用 Cargo 编译工程实际上还是调用 rustc 来完成的。如果我们想知道 cargo 在后面是如何调用 rustc 完
成编译的，可以使用 cargo build --verbose 选项查看详细的编译命令。

常用的 Cargo 命令：

一、cargo -h : 帮助命令

二、cargo new: 创建项目

三、cargo build: 编译项目

四、cargo run: 运行项目

五、cargo check: 只检查编译错误，而不做代码优化以及生成可执行程序，非常适合在开发过程中快速检查语法、类型错误。

六、cargo clean: 清理以前编译的结果。

七、cargo doc: 生成该项目的文档。

八、cargo test: 执行单元测试。

九、cargo bench: 执行 benchmark 性能测试。

十、cargo update: 升级所有依赖项的版本，重新生成 Cargo.lock 文件。

十一、cargo install: 安装可执行程序。这个命令非常有用，可以扩展 cargo 的子命令，为它增加新的功能。比如 可以使用 cargo install cargo-tree 命令，然后通过 cargo tree 打印依赖项的树形结构。

十二、cargo uninstall: 卸载可执行程序。

2、package 和 create

create 的作用：将相关功能组合到一个作用域内，便于在项目间进行共享，防止冲突。

①、crate 是一个二进制项(binary)或者库(library)。

②、crate root 是一个源文件，Rust 编译器以它为起始点，并构成你的 crate 的根模块(module)。

③、包*（package) 是提供一系列功能的一个或者多个 crate。一个包会包含有一个 Cargo.toml 文件，阐述如何去构建这些 crate。

包中可以包含至多一个库 crate(library crate)。包中可以包含任意多个二进制 crate(binary crate)，但是必须至少包含一个 crate（无论是库的还是二进制的）。

下面我们通过 Cargo 创建一个包。

$ cargo new my-project
     Created binary (application) `my-project` package
$ ls my-project
Cargo.toml
src
$ ls my-project/src
main.rs

可以看到Cargo 会给我们的包创建一个 Cargo.toml 文件，查看内容如下：

[package]
name = "my-project"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

我们会发现并没有提到 src/main.rs，因为 Cargo 遵循的一个约定：src/main.rs 就是一个与包同名的二进制 crate 的 crate 根。

同样的，Cargo 知道如果包目录中包含 src/lib.rs，则包带有与其同名的库 crate，且 src/lib.rs 是 crate 根。crate 根文件将由 Cargo 传递给 rustc 来实际构建库或者二进制项目。

在此，我们有了一个只包含 src/main.rs 的包，意味着它只含有一个名为 my-project 的二进制 crate。如果一个包同时含有 src/main.rs 和 src/lib.rs，则它有两个 crate：一个二进制的和一个库的，且名字都与包相同。

通过将文件放在 src/bin 目录下，一个包可以拥有多个二进制 crate：每个 src/bin 下的文件都会被编译成一个独立的二进制 crate。

3、module

模块 的作用：

①、在一个 crate 中，将代码进行分组，以提高可读性与重用性。

②、控制项目的访问权限（private/public），默认是私有（private）。

3.1 创建 mod

// 前台
mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}

        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}

        fn serve_order() {}

        fn take_payment() {}
    }
}

我们在 src 目录下创建了一个 lib.rs 文件，然后在里面添加上面的代码。

这里面我们定义一个模块，是以 mod 关键字为起始，然后指定模块的名字（这里叫做 front_of_house），并且用花括号包围模块的主体。在模块内，我们还可以定义其他的模块，就像本例中的 hosting 和 serving 模块。模块还可以保存一些定义的其他项，比如结构体、枚举、常量、特性、或者函数。

通过使用模块，我们可以将相关的定义分组到一起，并指出他们为什么相关。程序员可以通过使用这段代码，更加容易地找到他们想要的定义，因为他们可以基于分组来对代码进行导航，而不需要阅读所有的定义。程序员向这段代码中添加一个新的功能时，他们也会知道代码应该放置在何处，可以保持程序的组织性。

这个模块的树形结构如下：

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

4、path

上一节我们定义了模块以及如何创建模块，那么如何访问模块中某一项呢？

这就需要使用路径（path），就像在文件系统使用路径一样。如果我们想要调用一个函数，我们需要知道它的路径。

4.1 绝对路径和相对路径

• 绝对路径（absolute path）从 crate 根开始，以 crate 名或者字面值 crate 开头。
• 相对路径（relative path）从当前模块开始，以 self、super 或当前模块的标识符开头。

绝对路径和相对路径后都跟一个或多个由双冒号（::）分割的标识符。

// 前台模块
mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // 绝对路径
    crate::front_of_house::hosting::add_to_waitlist();

    // 相对路径
    front_of_house::hosting::add_to_waitlist();
}

PS：建议使用绝对路径，这样代码调用位置移动也不用修改。

4.2 使用 pub 关键字控制访问权限

上面的代码，我们编译，会报如下错误：

这是因为：

①、 Rust 中默认所有项（函数、方法、结构体、枚举、模块和常量）都是私有的。

②、父模块中的项不能使用子模块中的私有项，但是子模块中的项可以使用他们父模块中的项。

为了让上面的代码编译通过，我们可以使用关键字 pub 将 front_of_house 模块下的 hosting 模块定义为公共的。

mod front_of_house {
    pub mod hosting {
        fn add_to_waitlist() {}
    }
}

我们接着编译，发现还是报错：

看报错是因为 add_to_waitlist() 方法是私有的，我们只是给其父模块增加了 pub 关键字，这说明：

通过关键字 pub 使其模块公有，但是其内容默认还是私有的。

我们需要将 add_to_waitlist() 方法也加上 pub 关键字，才会编译通过。

4.3 使用 super 关键字表示父模块路径

super 关键字表示父模块路径，类似文件系统中的 .. 开头的语法。

fn serve_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::serve_order();
    }

    fn cook_order() {}
}

4.4 使用 use 关键字将路径引入作用域

前面例子中无论我们选择 add_to_waitlist 函数的绝对路径还是相对路径，每次我们想要调用 add_to_waitlist 时，都必须指定front_of_house 和 hosting。

pub fn eat_at_restaurant() {
    // 绝对路径
    crate::front_of_house::hosting::add_to_waitlist();

    // 相对路径
    self::front_of_house::hosting::add_to_waitlist();
}

那么有没有办法简化这个路径呢？

答案是：我们可以使用 use 关键字将路径一次性引入作用域，然后调用该路径中的项，就如同它们是本地项一样。

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

另外，use 也可以引用相对路径，并且也会检查路径私有性。

4.5 使用 as 关键字提供新的名称

as 关键字可以为引入的路径指定本地别名。

比如使用 use 将两个同名类型引入同一作用域，调用的时候就必须带上父路径，如果不想带上，可以给这两个同名类型起一个别名。

use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
    // --snip--
    Ok(())
}

fn function2() -> IoResult<()> {
    // --snip--
    Ok(())
}

4.6 使用 pub use 重新导出名称

使用 use 关键字，将某个名称导入当前作用域后，这个名称在此作用域中就可以使用了，但它对此作用域之外还是私有的。

如果想让其他人调用我们的代码时，也能够正常使用这个名称，就好像它本来就在当前作用域一样，那我们可以将 pub 和 use 合起来使用。这种技术被称为 “重导出（re-exporting）”：我们不仅将一个名称导入了当前作用域，还允许别人把它导入他们自己的作用域。

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
}

5、引入外部依赖

在Java项目中，我们引入外部依赖通常是在 pom.xml 文件中引入外部依赖。

在 rust 中，我们是在 Cargo.toml 文件中引入，比如引入一个随机数依赖：

rand = "0.8.3"

在 Cargo.toml 中加入 rand 依赖告诉了 Cargo 要从 crates.io 下载 rand 和其依赖，并使其可在项目代码中使用。

接着，为了将 rand 定义引入项目包的作用域，我们加入一行 use 起始的包名，它以 rand 包名开头并列出了需要引入作用域的项。

use std::io;
use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

6、嵌套路径来消除大量的use 行

当需要引入很多定义于相同包或相同模块的项时，可以进行合并。

①、比如：

use std::cmp::Ordering;
use std::io;

可以改写为：

use std::{cmp::Ordering, io};

②、层级共享

use std::io;
use std::io::Write;

可以改写为：

use std::io::{self, Write};

7、通过 * 运算符将所有的公有定义引入作用域

如果希望将一个路径下 所有 公有项引入作用域，可以指定路径后跟 *，glob 运算符：

use std::collections::*;

这个 use 语句将 std::collections 中定义的所有公有项引入当前作用域。

使用 * 运算符时要注意：这会使得我们难以推导作用域中有什么名称和它们是在何处定义的。

glob 运算符经常用于测试模块 tests 中，这时会将所有内容引入作用域。

用于预导入（prelude）模块。

8、将模块拆分成多个文件

当模块变多时（多个方法、结构体等），我们需要将它们的定义移动到单独的文件中，从而使代码更容易阅读。

这里需要注意两个点：

①、模块定义时，如果模块名后面是“;”，而不是代码块，那么rust 会从与模块同名的文件中加载内容。

②、模块树的结构不会变化。

比如，我们在 lib.rs 创建如下内容：

// 前台模块
mod front_of_house {
    pub mod hosting {
       pub fn add_to_waitlist() {
       }
    }
}

pub fn eat_at_restaurant() {
    // 绝对路径
    crate::front_of_house::hosting::add_to_waitlist();
    // 相对路径
    self::front_of_house::hosting::add_to_waitlist();
}

现在，我们想把 font_of_house 模块移动出去,需要进行两步操作：

一、在 src 目录下创建 font_of_house.rs 文件，内容如下：

pub mod hosting {
    pub fn add_to_waitlist() {
    }
}

二、lib.rs 改写

// 前台模块
mod front_of_house;

pub fn eat_at_restaurant() {
    // 绝对路径
    crate::front_of_house::hosting::add_to_waitlist();
    // 相对路径
    self::front_of_house::hosting::add_to_waitlist();
}

同理，如果我们还想把 hosting 里面的模块也提取出去，那该怎么办呢？

假设，我们直接在 src 目录下创建 hosting.rs 文件，然后看看编译结果：

这对应了我们前面说的模块树的结构是不变的，所以编译器是找 src/font_of_house 目录下的 hosting.rs 文件，我们不能将其放在 src 目录下。