当前位置：首页 > article >正文

Rust 中的模块系统：控制作用域与私有性

article 2025/2/5 10:40:44

模块、路径与 `use` 关键字简明速查

在开始具体案例之前，我们先来看看 Rust 模块系统的一些基础规则：

从 crate 根开始
编译器首先会在 crate 根（对于库 crate 默认是 src/lib.rs，对于二进制 crate 默认是 src/main.rs）中查找代码。
声明模块
在 crate 根中，可以使用 mod 关键字声明一个模块，例如：
```
mod garden;
```
编译器会在以下位置寻找 garden 模块的实现：
- 内联写在大括号中（代替分号）
- 文件 src/garden.rs
- 文件 src/garden/mod.rs
声明子模块
在非 crate 根文件中同样可以声明子模块，例如在 src/garden.rs 中：
```
mod vegetables;
```
编译器会依次在以下位置查找：
- 内联大括号中的代码
- 文件 src/garden/vegetables.rs
- 文件 src/garden/vegetables/mod.rs
路径访问模块中的代码
一旦模块被引入 crate 中，可以通过路径来访问其中的代码。例如，假设 Asparagus 类型定义在 src/garden/vegetables.rs 中，那么它的完整路径就是：
```
crate::garden::vegetables::Asparagus
```
私有性与公开性
默认情况下，模块中的代码对父模块是私有的。如果需要让模块或其中的项对外部可见，需要使用 pub 修饰：
```
pub mod garden;
pub fn some_function() { ... }
```
use 关键字
为了减少长路径的重复输入，可以在作用域内使用 use 关键字创建路径别名：
```
use crate::garden::vegetables::Asparagus;
```
从此之后，当前作用域只需使用 Asparagus 即可引用该类型。

实战案例：构建一个示例项目

让我们通过一个示例项目来深入了解模块系统的应用。假设我们创建了一个二进制 crate，名为 backyard，目录结构如下：

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

crate 根：src/main.rs
这是项目的入口文件。在这里，我们会用 pub mod garden; 告诉编译器在 src/garden.rs 中查找 garden 模块的定义。
模块实现：src/garden.rs
在这个文件中，可以继续声明子模块，例如：
```
pub mod vegetables;
```
编译器会自动查找 src/garden/vegetables.rs 中的实现。
子模块：src/garden/vegetables.rs
在这里可以定义 vegetables 模块中具体的结构体、函数等。

这种文件和模块的组织方式，使得代码结构与文件目录结构非常接近，方便开发者理解和维护项目。

分组相关代码：以餐厅系统为例

模块不仅仅是为了分散代码文件，更重要的是帮助我们将相关代码进行逻辑分组，并明确其作用域和公开性。下面以一个餐厅系统为例，说明如何利用模块划分前台（front of house）和后台（back of house）的功能。

创建项目
运行以下命令创建一个新的库 crate：
```
cargo new restaurant --lib
```

定义模块结构
在 src/lib.rs 中，我们可以定义如下模块结构：

pub mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {
            // 实现细节
        }

        fn seat_at_table() {
            // 仅内部使用
        }
    }

    pub mod serving {
        pub fn take_order() {
            // 实现细节
        }

        pub fn serve_order() {
            // 实现细节
        }

        pub fn take_payment() {
            // 实现细节
        }
    }
}

如上所示：

front_of_house 模块对外公开（pub mod），表示餐厅的前台部分可以被外部调用。
前台模块下的子模块 hosting 和 serving 也分别使用 pub mod 进行声明，其中某些函数（例如 seat_at_table）保持私有，仅用于模块内部调用。

模块树示意
以上代码构成了如下的模块树：

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

这种分组方式不仅使代码逻辑清晰，而且对外暴露的接口也非常明确。

使用 use 关键字简化调用
在其他模块或二进制 crate 中使用餐厅系统的功能时，可以利用 use 来引入模块：
```
use crate::front_of_house::hosting;

fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}
```
这大大减少了重复书写长路径的麻烦，并且使代码更易读。