本文内容
这篇文章是实战性质的，也就是说原理部分较少，属于经验总结，rust对于模块的例子太少了。rust特性比较多（悲），本文的内容可能只是一部分，实现方式也不一定是这一种。
关于 rust 模块的相关内容，准确来说：怎么在源码中引用其他模块的内容。
- 关于
mod、use、as这几个关键字（文件名） - 关于
mod.rs文件 - 关于
self、super、crate这几个路径关键字 worksapce：本文不讨论，狭义上指的是cargo的[workspace]部分： 可参见 The [workspace] sectionpackage： 狭义上指的是cargo的[package]部分，参见 The [package] sectioncrate：参见下文 关于 create 的定义和 cargo 管理下的 cratemodule：本文的重点， crate 里 会有多个 module，文本讨论重点就是 mod 之间相互引用的问题。
一、mod 关键字和 mod.rs 文件，其他普通文件 foo.rs 等
引用模块要搞清楚的：
- 是在哪里引用的，也就要引用的文件的位置
- 需要引用那个模块，跟这个文件的相对位置和绝对位置是什么
mod 关键字：
- 用来声明，表现方式是包裹一个代码块。也就是说这个代码块会成为一个单独的模块。
mod xxx { <rust语句块> }：内部写 rust 语句 。见 例一#[path="...xxxx.rs"] mod xxx;：使用 path 属性 ，使用见例二mod xxx { include!("...xxxx.rs") }：内部配合include!宏，使用见例二
- 用来声明（“引用”）其他“模块”。（一个文件隐含的表示为一个mod）
假设使用mod toy;语句来引入一个模块，实际上这跟你在哪里写的这个语句有关系有关- 把当前的文件所在位置分为两类， 类型A：位置在
src/main.rs、src/lib.rs或者xxx/.../mod.rs位置上的文件; 类型B: 位置不在1中的文件。 - 在位置类型 A 的文件使用代码
mod toy;，你实际上在告诉编译器，你需要的模块是与此文件同级的toy.rs或者toy/mod.rs文件 。编译器会自己找下这两个被引用的位置，如果两个位置都有文件，则报错。见 例三 - 在位置类型 B 的文件使用代码
mod toy;，你实际上在告诉编译器，你需要的模块是与此文件（假设文件名为foo.rs）同级的foo文件夹下的foo/toy.rs或者foo/toy/mod.rs文件。编译器会自己找下这两个被引用的位置，如果两个位置都有文件，则报错。 见 例四
- 把当前的文件所在位置分为两类， 类型A：位置在
二、使用 use 和 as 关键字缩短导入语句，或者导出模块内容
use 关键字也有两个作用
- 缩短语句，使用 use 为当前文件缩短长语句，减少重复性的代码，见 例子五
- 配合
as关键字一起使用，进一步减少重复代码，或者防止名字重复，或者取个顺眼的名字 例子六 - 打包其他模块的内容，当做本模块的内容一起导出。见 例子七
三、使用 super 和 crate 进行相对路径和绝对路径（顶级路径）的访问
如果我们想要调用一个函数，我们需要知道它的路径。路径有两种形式：
- 绝对路径（absolute path）从 crate 根部开始，以 crate 名或者字面量 crate 开头。 见例八
- 相对路径（relative path）从当前模块开始，以 self、super 或当前模块的标识符开头。
见文档： https://rustwiki.org/zh-CN/book/ch07-03-paths-for-referring-to-an-item-in-the-module-tree.html
四、关于 create 的定义和 cargo 管理下的 crate
我们都知道通过 cargo 创建出的工程中 src/main.rs 就是程序的入口，但是还有更多的使用方式。
- rustc 命令 ： rust编译器，就算没有cargo也可以生成程序，但是比较麻烦，这些都让cargo来处理就好
- cargo 命令 ： 项目管理工具
下面就是一些问题了
- 什么是 create ？ rustc 的编译入口文件，这个文件就被当做 crate 文件。
- crate 类型： 有多种，最常见的是
bin和lib，其他类型参见 rust参考手册-链接 - cargo 怎么定义工程项目中哪些是需要编译的 crate 的？ 参见： cargo手册-项目布局
▾ src/ # 包含源文件的目录
lib.rs # 库和包的主要入口点
main.rs # 包生成可执行文件的主要入口点
▾ bin/ # （可选）包含其他可执行文件的目录
*.rs
▾ */ # （可选）包含多文件可执行文件的目录
main.rs
▾ examples/ # （可选）示例
*.rs
▾ */ # （可选）包含多文件示例的目录
main.rs
▾ tests/ # （可选）集成测试
*.rs
▾ */ # （可选）包含多文件测试的目录
main.rs
▾ benches/ # （可选）基准
*.rs
▾ */ # （可选）包含多文件基准的目录
main.rs
五、例子
例一：单文件，主函数和 toy 模块
- 注意
run函数需要加pub关键字，否则不会被导出
src/main.rs
mod toy {
pub fn run() {
println!("run toy");
}
}
fn main() {
toy::run();
}
输出
run toy
例二：两个文件，主函数和另一个文件夹 toy 模块
src/toy_implements.rs
pub fn run() {
println!("run toy_impl !");
}
src/main.rs
mod toy1 { // 方法1： 使用 include!
include!("./toy_implements.rs");
}
#[path ="./toy_implements.rs"]
mod toy2; // 方法2： 使用 path 属性定位文件位置
fn main() {
toy1::run();
toy2::run();
}
输出
run toy_impl !
run toy_impl !
例三：在 main.rs 中使用 mod toy;
src/toy.rs
pub fn run() {
println!("run toy_impl !");
}
src/main.rs
mod toy;
fn main() {
toy::run();
}
输出
run toy_impl !
例四：在 src/foo.rs 中使用 mod toy;
src/foo/toy.rs
pub fn run() {
println!("run toy_impl !");
}
src/foo.rs
mod toy;
fn say_hi() {
toy::run();
}
输出
run toy_impl !
例五：use 指令
之前，我们使用了 toy::run() 来调用 run 函数。现在，我们使用 use 关键字来导入 toy 模块里的内容，这样就能在 main 函数中直接使用
src/foo.rs
mod toy {
pub fn run() { // 注意使用 pub 关键字
println!("run toy");
}
}
fn main() {
use toy::*; // 使用 use 导入 toy 模块里的内容
run(); // 直接调用
}
例六： 在as配合use指令
src/foo.rs
mod toy {
pub fn run() { // 注意使用 pub 关键字
println!("run toy");
}
}
fn main() {
use toy::run as toy_run; // 使用 use + as 导入 toy 模块里的内容
toy_run();
}
例七： 使用pub use命令在mod.rs合并打包其他模块的东西
src/toy/runner.rs
pub fn dog_run() { println!("dog is run !"); }
src/toy/fly.rs
pub fn fly_bird() { println!("bird is fly !"); }
src/toy/bear.rs
pub fn bear_eat() { println!("bear is eat fish !"); }
pub fn bear_sleep() { println!("bear is go sleep !"); }
src/toy/mod.rs
mod runner; // 引入同级 runner.rs 文件
mod fly; // 引入同级 fly.rs 文件
mod bear; // 引入同级 bear.rs 文件
pub use runner::dog_run; // 声明（导出） dog_run 函数
pub use fly::fly_bird as now_fly_brid; // 声明（导出） fly_bird 函数，并重命名为 now_fly_brid
pub use bear::*; // 声明（导出） dog_run 函数
src/main.rs
mod toy;
fn main() {
toy::dog_run();
toy::now_fly_brid();
toy::bear_eat();
toy::bear_sleep();
}
输出
dog is run !
bird is fly !
bear is eat fish !
bear is go sleep !
例七： 使用pub mod导出内部包，使用 crate 引用顶部内容
src/toy/cube/mod.rs
pub fn get_size() {
println!("size is in main");
crate::top_size(); // 必不可少的 crate 关键字
}
src/toy/mod.rs
pub mod cube;
src/main.rs
mod toy;
fn top_size() {
println!("top size one !")
}
fn main() {
toy::cube::get_size();
}
输出
size is in main
top size one !
参考文献
！！强烈推荐看下面的参考做补充！！
- 模块的官方参考： https://rustwiki.org/zh-CN/reference/items/modules.html
- Rust 程序设计语言（7. 使用包、Crate和模块管理不断增长的项目）： https://rustwiki.org/zh-CN/book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html
- Rust 模块和文件（译文）： https://zhuanlan.zhihu.com/p/73544030
- Rust 模块和文件（原文）： https://amos.me/blog/2019/rust-modules-vs-files/
- crate: https://rustwiki.org/zh-CN/rust-by-example/crates.html
- crate 类型： https://rustwiki.org/zh-CN/reference/linkage.html