Rust / 系统课时
定义模块
定义模块
模块用于把一个 crate 内的代码拆成有层次的命名空间。掌握 mod、文件映射和可见性后,你可以把单文件程序拆成多文件结构,同时保持调用路径清晰,并避免把模块声明与 use 导入混为一谈。
学习目标
- 使用
mod从 crate root 建立模块树 - 将父模块与子模块拆分到不同源文件
- 正确使用
pub和路径访问跨模块函数
模块树从 crate root 开始
Rust 不会因为目录里出现了 .rs 文件就自动把它加入项目。crate root 必须先用 mod 声明直接子模块,子模块再继续声明自己的下级模块;编译器据此建立模块树并定位对应文件。

下面使用现代常见的文件布局:
src/main.rs是 binary crate 的 crate root,声明networksrc/network.rs定义network,并声明子模块clientsrc/network/client.rs定义network::client
这种布局比把所有实现都写进 crate root 更容易维护,也避免为每个模块都使用旧式的 mod.rs 文件。
建立一个可运行的多文件示例
src/main.rs:
// 声明模块后,编译器才会加载 src/network.rs
mod network;
fn main() {
network::connect();
network::client::send();
}src/network.rs:
// pub 让 crate root 可以继续访问 network::client
pub mod client;
pub fn connect() {
println!("connect");
}src/network/client.rs:
// 对父模块之外暴露发送函数
pub fn send() {
println!("send");
}在 package 根目录运行:
cargo run -q预期输出
connect
send这里的 mod network; 负责把模块加入模块树;pub mod client; 让 client 可以从 network 外部访问;两个函数上的 pub 则允许父模块之外的代码调用它们。
mod、use 与 pub 各做一件事
mod 是定义或声明模块,决定模块树里有没有这个节点。use 是把已有路径引入当前作用域,只改变写法,不会创建模块。pub 是控制可见性,决定某个模块或项能否被更外层代码访问。
例如已经有 network::client::send 后,可以在 main.rs 中写 use network::client;,随后调用 client::send();但如果删掉最初的 mod network;,仅靠 use 无法让编译器发现 src/network.rs。
文件拆分时的检查顺序
遇到“文件明明存在但模块找不到”时,先从 crate root 沿模块树逐级检查 mod 声明,再核对文件路径,最后检查 pub。这三类问题分别对应“模块未加入树”“源文件位置不匹配”和“模块存在但不可见”,不要只靠反复修改 use 语句碰运气。
当模块层级变深时,优先让文件结构与模块树保持一致;这样看到 network::client 就能快速定位到 src/network/client.rs,代码导航和重构都会更直接。