Rust 模块系统

学习mod · 难度：进阶 · +15XP

Rust 模块系统

Rust 的模块系统用于组织和封装代码，它通过 包（Packages）、Crate（箱）、模块（Modules）和路径（Paths）这四个层级来管理代码的结构与可见性。良好的模块化设计可以让大型 Rust 项目保持清晰、有序，并且通过可见性规则（pub）精确控制哪些代码对外暴露。

定义模块

使用 mod 关键字定义模块。模块可以嵌套，形成树状结构。每个模块默认是私有的，其中的函数、结构体等也需要显式标注 pub 才能被外部访问。

// 内联定义模块
mod math {
    pub fn add(a: i32, b: i32) -> i32 {
        a + b
    }
    fn helper() {  // 私有函数，外部无法访问
        println!("这是一个辅助函数");
    }
    pub mod advanced {  // 嵌套模块
        pub fn multiply(a: i32, b: i32) -> i32 {
            a * b
        }
    }
}
fn main() {
    let result = math::add(5, 3);
    println!("5 + 3 = {}", result);
    let product = math::advanced::multiply(4, 6);
    println!("4 * 6 = {}", product);
    // math::helper();  // 错误！helper() 是私有的
}

文件与目录模块

文件/目录结构	模块声明	说明
my_module.rs	mod my_module;	模块定义在单独文件中
my_module/mod.rs	mod my_module;	模块是一个目录，主文件为 mod.rs
my_module/xxx.rs	在 my_module 内: pub mod xxx;	子模块文件
src/lib.rs	库 crate 的根	定义库的公共 API
src/main.rs	二进制 crate 的根	程序的入口点

// === src/main.rs ===
mod database;       // 加载 src/database.rs 或 src/database/mod.rs
mod utils;           // 加载 src/utils.rs
fn main() {
    database::connect();
    utils::format::pretty_print("Hello");
}

use 关键字与路径引入

use 关键字用于将模块路径引入当前作用域，避免每次都写完整的路径。pub use 可以将子模块中的内容重新导出（re-export），从而简化外部用户的使用路径。

// 引入模块
use std::collections::HashMap;
use std::io::{self, Read, Write};  // 一次性引入多个
use std::fs::*;                    // 引入 fs 中所有公开项（谨慎使用）
// 重新导出（在 lib.rs 中常用）
pub use crate::models::User;
pub use crate::services::user_service;
fn main() {
    let mut map = HashMap::new();  // 无需 std::collections::HashMap
    map.insert("key", "value");
}

super 与 crate 相对路径

除了绝对路径（从 crate 根开始），Rust 还支持 super（父模块）和 crate（根模块）两种相对路径，让模块间的引用更加灵活。

1. 创建一个包含两个模块的项目：math（加减乘除）和 string_util（字符串操作），分别放在独立文件中
2. 在 math 模块中设置部分函数为私有，验证外部能否访问
3. 使用 pub use 重新导出一个深层嵌套的公共接口到 crate 根层级
4. 在一个子模块中使用 super:: 调用父模块中的函数
5. 使用 mod tests + #[cfg(test)] 为模块编写单元测试