mod 模块定义 ​

什么是模块 ​

模块(Module)是 Rust 中组织代码的基本单元。用 mod 关键字定义一个模块,把相关的函数、结构体、枚举、常量等组织在一起。模块提供命名空间隔离和可见性控制,避免命名冲突,让代码结构清晰。

rust
// 定义一个内联模块
mod math {
    pub fn add(a: i32, b: i32) -> i32 {
        a + b
    }

    pub fn multiply(a: i32, b: i32) -> i32 {
        a * b
    }

    // 私有函数,模块外部不能访问
    fn helper() {
        println!("这是内部辅助函数");
    }
}

fn main() {
    // 通过模块路径调用
    println!("3 + 4 = {}", math::add(3, 4));
    println!("3 * 4 = {}", math::multiply(3, 4));
    // math::helper();  // 编译错误:helper 是私有的
}

内联模块 ​

内联模块直接写在当前文件中,用花括号包围模块内容。

rust
mod animal {
    // 公开的结构体
    pub struct Dog {
        pub name: String,
        pub breed: String,
        age: u8,  // 私有字段
    }

    impl Dog {
        // 公开的构造函数
        pub fn new(name: &str, breed: &str, age: u8) -> Dog {
            Dog {
                name: name.to_string(),
                breed: breed.to_string(),
                age,
            }
        }

        // 公开方法
        pub fn bark(&self) {
            println!("{} 汪汪叫!", self.name);
        }

        // 私有方法
        fn secret(&self) {
            println!("{} 的年龄是 {}", self.name, self.age);
        }

        // 公开方法可以内部调用私有方法
        pub fn info(&self) {
            println!("名字:{},品种:{}", self.name, self.breed);
            self.secret();  // 模块内部可以调用私有方法
        }
    }
}

fn main() {
    let dog = animal::Dog::new("旺财", "柴犬", 3);
    dog.bark();
    dog.info();
    // dog.secret();  // 编译错误:私有方法
    // println!("{}", dog.age);  // 编译错误:私有字段
}

嵌套模块 ​

模块可以嵌套,形成模块树。

rust
mod network {
    pub mod http {
        pub fn get(url: &str) -> String {
            format!("GET 请求:{}", url)
        }

        pub fn post(url: &str, body: &str) -> String {
            format!("POST 请求:{}, body={}", url, body)
        }
    }

    pub mod tcp {
        pub fn connect(addr: &str) -> String {
            format!("TCP 连接到 {}", addr)
        }
    }

    // 私有子模块
    mod internal {
        pub fn log(msg: &str) {
            println!("[内部日志] {}", msg);
        }
    }

    // 父模块可以访问私有子模块
    pub fn init() {
        internal::log("网络模块初始化");
    }
}

fn main() {
    println!("{}", network::http::get("https://example.com"));
    println!("{}", network::tcp::connect("127.0.0.1:8080"));
    network::init();
    // network::internal::log("test");  // 编译错误:internal 是私有模块
}

文件模块 ​

当模块内容较多时,可以把模块的代码放到独立的文件中。在父模块中用 mod 模块名;(注意分号)来声明,编译器会自动去找对应的文件。

文件查找规则:

声明位置mod utils; 查找的文件
src/main.rs 或 src/lib.rssrc/utils.rs 或 src/utils/mod.rs
src/network.rssrc/network/utils.rs
src/network/mod.rssrc/network/utils.rs
rust
// 文件:src/main.rs
mod utils;      // 加载 src/utils.rs
mod services;   // 加载 src/services.rs 或 src/services/mod.rs

fn main() {
    utils::greet("Rust");
    services::process();
}
rust
// 文件:src/utils.rs
pub fn greet(name: &str) {
    println!("你好,{}!", name);
}
rust
// 文件:src/services.rs(或 src/services/mod.rs)
pub fn process() {
    println!("处理服务请求");
}

模块的可见性规则 ​

Rust 的默认可见性是私有的。以下是核心规则:

  • 模块内的项默认是私有的,外部不可访问
  • 用 pub 标记的项可以从外部访问
  • 子模块可以访问父模块的所有项(包括私有项)
  • 父模块不能直接访问子模块的私有项
rust
mod outer {
    fn private_fn() {
        println!("outer 的私有函数");
    }

    pub fn public_fn() {
        println!("outer 的公开函数");
        private_fn();  // 同模块内可以调用私有函数
    }

    pub mod inner {
        pub fn call_parent() {
            // 子模块可以访问父模块的私有项
            super::private_fn();
        }

        fn inner_private() {
            println!("inner 的私有函数");
        }
    }

    pub fn try_call_inner_private() {
        // inner::inner_private();  // 编译错误:父模块不能访问子模块的私有项
    }
}

fn main() {
    outer::public_fn();
    outer::inner::call_parent();
}

基本示例 ​

组织一个简单的应用结构:

rust
// 配置模块
mod config {
    pub struct AppConfig {
        pub app_name: String,
        pub version: String,
        pub debug: bool,
    }

    impl AppConfig {
        pub fn default() -> Self {
            AppConfig {
                app_name: String::from("MyApp"),
                version: String::from("1.0.0"),
                debug: false,
            }
        }

        pub fn with_debug(mut self) -> Self {
            self.debug = true;
            self
        }
    }
}

// 日志模块
mod logger {
    use super::config::AppConfig;

    pub fn init(config: &AppConfig) {
        if config.debug {
            println!("[DEBUG] 日志系统已初始化 - {}", config.app_name);
        } else {
            println!("[INFO] 日志系统已初始化");
        }
    }

    pub fn info(msg: &str) {
        println!("[INFO] {}", msg);
    }

    pub fn error(msg: &str) {
        println!("[ERROR] {}", msg);
    }
}

// 业务逻辑模块
mod service {
    pub fn start() {
        super::logger::info("服务启动中...");
        // 业务逻辑
        super::logger::info("服务已就绪");
    }
}

fn main() {
    let config = config::AppConfig::default().with_debug();
    logger::init(&config);
    service::start();
    logger::info("应用运行中");
}

常见问题 ​

问题一:mod 和 use 有什么区别?

关键字作用类比
mod声明/定义一个模块创建一个文件夹
use导入模块中的项到当前作用域创建一个快捷方式

mod 是告诉编译器"这里有一个模块",use 是"把模块里的东西引入当前作用域方便使用"。

问题二:什么时候用内联模块,什么时候用文件模块?

代码量少(几十行以内)用内联模块,代码量大时放到独立文件中。一般来说,正式项目中除了测试模块(#[cfg(test)] mod tests),大多数模块都用文件形式。

问题三:mod.rs 和同名文件有什么区别?

两种方式等价。比如 src/utils/mod.rs 和 src/utils.rs 都可以作为 utils 模块的入口。现在推荐用 utils.rs 而不是 utils/mod.rs,更简洁。

问题四:为什么子模块能访问父模块的私有项?

这是 Rust 的设计选择——模块的可见性边界是"向外"的。子模块是父模块的一部分,自然可以访问内部的一切。但外部代码(包括父模块)不能访问子模块的私有项。

适用场景 ​

  • 代码组织:把相关的类型和函数放在同一个模块中
  • 命名空间:避免不同功能的函数名冲突
  • 可见性控制:隐藏实现细节,只暴露公开接口
  • 代码拆分:大文件拆成多个模块文件,便于维护

注意事项 ​

  • 模块内的项默认私有,需要 pub 才能从外部访问
  • mod 名字; 声明文件模块,编译器自动查找对应的 .rs 文件
  • 不要忘记在父文件中声明 mod,否则 .rs 文件不会被编译
  • 子模块用 super:: 访问父模块,用 crate:: 从 crate 根开始访问
  • 结构体的字段默认也是私有的,即使结构体本身是 pub 的
  • 推荐用 模块名.rs 而不是 模块名/mod.rs(除非有子模块文件)

总结 ​

mod 关键字用来定义模块,是 Rust 代码组织的基础。模块可以内联定义(用花括号包围)或放在独立文件中(用分号声明)。模块提供命名空间隔离和可见性控制——默认所有项都是私有的,用 pub 标记公开。模块可以嵌套形成树形结构,子模块能访问父模块的所有项,但父模块不能访问子模块的私有项。文件模块的查找遵循固定规则,编译器根据模块名自动查找对应的 .rs 文件。