mod 模块定义
什么是模块
模块(Module)是 Rust 中组织代码的基本单元。用 mod 关键字定义一个模块,把相关的函数、结构体、枚举、常量等组织在一起。模块提供命名空间隔离和可见性控制,避免命名冲突,让代码结构清晰。
// 定义一个内联模块
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 是私有的
}内联模块
内联模块直接写在当前文件中,用花括号包围模块内容。
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); // 编译错误:私有字段
}嵌套模块
模块可以嵌套,形成模块树。
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.rs | src/utils.rs 或 src/utils/mod.rs |
src/network.rs | src/network/utils.rs |
src/network/mod.rs | src/network/utils.rs |
// 文件:src/main.rs
mod utils; // 加载 src/utils.rs
mod services; // 加载 src/services.rs 或 src/services/mod.rs
fn main() {
utils::greet("Rust");
services::process();
}// 文件:src/utils.rs
pub fn greet(name: &str) {
println!("你好,{}!", name);
}// 文件:src/services.rs(或 src/services/mod.rs)
pub fn process() {
println!("处理服务请求");
}模块的可见性规则
Rust 的默认可见性是私有的。以下是核心规则:
- 模块内的项默认是私有的,外部不可访问
- 用
pub标记的项可以从外部访问 - 子模块可以访问父模块的所有项(包括私有项)
- 父模块不能直接访问子模块的私有项
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();
}基本示例
组织一个简单的应用结构:
// 配置模块
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 文件。