3.3 模块与包的组织

随着项目规模的增长，将所有代码写在一个文件里会变得难以维护。Rust 提供了一套强大的模块系统，用于组织代码、控制作用域和封装实现细节。这套系统由 包（Packages）、Crate 和 模块（Modules） 三个核心概念组成。

3.3.1 包（Package）与 Crate

在深入模块之前，我们需要先理解 Rust 中代码分发和编译的基本单元。

  • Crate：Crate 是 Rust 编译器一次处理的最小代码单元。它可以是一个二进制项目（可执行文件）或一个库项目（供其他程序使用的代码）。每个 Crate 都有一个根文件（如 main.rs 或 lib.rs），编译器从此文件开始编译。
  • 包（Package）：一个包是一个包含 Cargo.toml 文件的目录，用于描述如何构建一个或多个 Crate。一个包最多只能包含一个库 Crate，但可以包含任意多个二进制 Crate。通常，一个包会包含一个库 Crate 和多个二进制 Crate，或者只包含一个二进制 Crate。

当你使用 cargo new my_project 创建一个新项目时，Cargo 会创建一个包。默认情况下，它会在 src/main.rs 中生成一个二进制 Crate。

3.3.2 模块（Module）的定义与作用

模块是 Rust 中组织代码的核心机制。它允许你将一个 Crate 内的代码分组，并控制代码的可见性（公有或私有）。模块的定义使用 mod 关键字。

示例：定义一个模块

// src/lib.rs 或 src/main.rs

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() {}
    }
}

在这个例子中，我们在 Crate 根文件（lib.rs 或 main.rs）中定义了一个名为 front_of_house 的模块。在这个模块内部，我们又定义了两个子模块：hosting 和 serving。模块可以嵌套，形成一棵模块树。

3.3.3 模块树与路径

模块之间通过路径来引用。路径有两种形式：

  • 绝对路径：从 Crate 根开始，使用 Crate 名或字面量 crate 开头。例如：crate::front_of_house::hosting::add_to_waitlist。
  • 相对路径：从当前模块开始，使用 self、super 或当前模块的标识符开头。例如：self::hosting::add_to_waitlist 或 super::serving::take_order。

self 代表当前模块，super 代表父模块。

3.3.4 可见性与 pub 关键字

Rust 中，模块内的所有项（函数、结构体、枚举、常量、其他模块等）默认都是私有的。私有意味着只有当前模块及其子模块可以访问。要使其对外部可见，需要使用 pub 关键字。

示例：使用 pub 暴露路径

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();

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

在这个例子中，我们将 hosting 模块和 add_to_waitlist 函数都标记为 pub，这样 eat_at_restaurant 函数才能访问它们。如果只将 hosting 模块设为 pub，但 add_to_waitlist 函数仍然是私有的，那么外部代码依然无法调用它。

3.3.5 使用 use 关键字引入路径

为了简化路径的使用，Rust 提供了 use 关键字。use 可以将一个路径引入当前作用域，之后就可以直接使用该路径的短名称。

示例：使用 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();
    hosting::add_to_waitlist();
}

习惯用法：

  • 当引入函数时，通常引入到其父模块（如 use crate::front_of_house::hosting;），然后通过 hosting::function_name 调用。
  • 当引入结构体、枚举或其他项时，通常直接引入该项本身（如 use std::collections::HashMap;）。

3.3.6 模块文件系统

为了管理大型项目，Rust 允许将模块定义在单独的文件中。

规则：

  • 如果一个模块名为 my_module，且没有子模块，则其内容可以放在 my_module.rs 文件中。
  • 如果一个模块有子模块，则需要创建一个名为 my_module 的目录，并在该目录中放置一个 mod.rs 文件来定义模块及其子模块。

示例：

假设我们有以下目录结构：

src/
├── front_of_house/
│   ├── mod.rs
│   ├── hosting.rs
│   └── serving.rs
└── lib.rs
  • lib.rs 中声明：mod front_of_house;
  • front_of_house/mod.rs 中声明：pub mod hosting; 和 pub mod serving;
  • front_of_house/hosting.rs 中包含 add_to_waitlist 等函数的定义。
  • front_of_house/serving.rs 中包含 take_order 等函数的定义。

这种结构使得模块的层次关系与文件系统的目录结构一一对应，极大地提高了代码的可组织性和可读性。

3.3.7 使用 pub use 重导出

pub use 允许你将一个路径引入当前作用域，并使其对其他人可用。这常用于创建一个更友好的公共 API，隐藏内部模块的复杂结构。

// front_of_house/hosting.rs
pub fn add_to_waitlist() {}

// lib.rs
mod front_of_house;

pub use crate::front_of_house::hosting::add_to_waitlist;

// 外部用户现在可以直接调用 add_to_waitlist()，而不需要知道 hosting 模块的存在

总结

模块与包的组织是 Rust 项目结构化的基石。通过理解 包、Crate、模块、路径、可见性 和 文件系统 之间的关系，你可以构建出清晰、可维护且易于扩展的 Rust 项目。合理使用 mod、pub、use 和文件系统，是成为一名高效 Rust 开发者的必备技能。

Last Updated::