Rust模块文件查找的精确规则与执行逻辑问询

一、Crate根基础规则 #

• Crate根是编译入口文件（如src/main.rs对应二进制crate，src/lib.rs对应库crate），无需用mod声明，是整个crate模块树的根节点。
• 所有非根模块必须通过mod声明挂载到模块树，才能被Rust识别。

二、模块声明与文件映射规则 #

当在某模块文件中写mod <name>;或mod <name> { ... }时，Rust按以下逻辑查找对应文件：

1. 解析mod <name>中的<name>，检查当前模块的同级目录：
   • 优先查找<name>.rs文件，存在则该文件内容即为该模块代码。
   • 若不存在<name>.rs，则查找<name>/mod.rs文件，该文件内容作为模块代码，同时<name>目录下的文件可作为该模块的子模块。
2. 禁止同时存在<name>.rs和<name>/mod.rs，否则编译报错。
3. 若使用mod <name> { ... }内联写法（直接在当前文件写模块内容），则不查找外部文件，内联内容优先。

三、::路径解析规则 #

使用a::b::c这类路径引用模块或项时，Rust查找步骤：

1. 判定路径起始类型：
   • 路径以::开头（如::std::io）：从Crate根开始查找。
   • 路径以模块名开头（如my_mod::sub_mod）：从当前模块的同级模块开始查找；若当前模块无该直接子模块，则向上遍历父节点，直至Crate根。
   • 路径以self::开头：限定从当前模块内部查找；以super::开头：限定从当前模块的父模块查找。
2. 路径中每一层::对应模块树层级：
   • 如a::b::c，先找到模块a，再在a的子模块中找b，最后在b的子模块中找c。
   • 每一层模块都需符合文件映射规则（要么有对应.rs文件，要么有含mod.rs的目录，或是内联模块）。

四、use语句的辅助规则 #

use仅创建路径别名，不改变核心查找规则：

• use a::b::c;后可直接用c引用，但Rust仍按上述路径规则定位a::b::c对应的模块/项。
• use语句的路径解析规则与直接引用完全一致，仅简化后续写法。

五、工作区与子Crate的特殊规则 #

• 工作区中每个子Crate是独立模块树，彼此模块不自动共享，需通过Cargo.toml声明依赖后，用<crate_name>::...路径引用。
• 子Crate的模块查找规则与单个Crate完全一致，各有独立的Crate根。

内容的提问来源于stack exchange，提问作者Test