1. 1.94 版本下的模块系统mod.rs 与新式同构文件的取舍先说一个很多人纠结的问题到了 Rust 1.94 这个版本mod.rs到底还有没有存在的必要我的回答是它和同构文件方案比如network.rs配合network/目录在编译器层面完全兼容两者都合法都不被弃用。但如果你问我新建项目用什么我会毫不犹豫地选同构文件。这不是为了赶时髦而是这些年项目踩坑踩出来的实际体会。1.1 mod.rs 统治时期目录模块的标准入口如果你翻过 2015 edition 时代的 Rust 项目一定对这样的目录结构非常熟悉src/ ├── main.rs └── network/ ├── mod.rs ├── protocol.rs └── tcp.rs当时官方文档的推荐做法是一个目录要作为模块入口就放一个mod.rs文件。mod.rs的地位相当于其他语言里包的__init__.py或index.js它负责两件事声明目录内部的子模块以及书写模块自身要暴露的内容。// src/network/mod.rs pub mod protocol; pub mod tcp; pub fn connect() - bool { // 模块自身的逻辑可以放这里 true }之所以会设计成这样是因为编译器需要一个稳定、可预测的文件查找约定。你写mod network;编译器就往network.rs和network/mod.rs两个位置找。在那个年代官方把mod.rs当成一种标准形态写进了文档社区项目也默契地遵守久而久之便形成了习惯。这种做法的好处是规则极简看到一个目录进去就有mod.rs模块树和目录树一一对应。但它的缺点也在项目变大之后越来越明显。最典型的就是编辑器体验一个大型项目里十几个mod.rs名字一模一样光凭文件名根本看不出它属于哪一层。改代码的时候你得先点开文件确认所在的目录才能判断这个文件是不是你想找的那个。这种心智负担不算致命但日积月累非常磨损效率。1.2 同构文件崛起从 2018 edition 延续至今的推荐方案2018 edition 带来了一个关键变化官方把模块文件查找规则修订为mod foo;时优先查找foo.rs找不到再找foo/mod.rs。其实编译器在更早的版本里就支持这种查找顺序但从 2018 edition 开始官方明确把“同构文件”作为推荐风格写进了文档一系列工具链也随之围绕新风格做优化。新版的组织方式长这样src/ ├── main.rs ├── network.rs └── network/ ├── protocol.rs └── tcp.rsnetwork.rs既是模块入口也是模块自身逻辑的载体network/目录里放子模块文件。相比之下旧式写法把“模块自身逻辑”和“子模块声明”全都堆在mod.rs一个文件里文件一长就分不清主次。新式写法把入口文件和实现文件合二为一目录里只留下真正意义上的子模块整体结构清晰非常多。我在 1.94 上实际测试了两种混用方式编译器行为完全一致在同一项目中顶层模块用同构文件子模块用mod.rs只要路径和声明对得上都能正常编译。所以迁移不必一刀切比较稳妥的做法是新模块一律用同构文件老模块如果已经在mod.rs体系下稳定运行暂时不动等下次重构时再顺手迁移。这里顺便补充一个判断标准只要一个模块的下面还有多个子模块文件需要组织用同构文件就是最优解。如果模块很小、本身没有任何子目录那直接用单个文件即可连配套目录都不用建。2. 模块系统的底层规则路径、可见性与重导出文件结构只是皮路径和可见性才是骨。我见过太多新手把目录建得规规矩矩可一写代码就卡在“为什么这个类型访问不到”“为什么 use 的路径解析不了”这些基础问题上。这一节把三条底层规则讲透它们才是模块化的真正核心。2.1 三种路径基点怎么选Rust 模块路径有三种起点crate根、当前模块、父模块。对应到代码里就是crate::、self::、super::。它们的使用场景完全不同。// src/network/protocol.rs use crate::config::Config; // 从 crate 根出发绝对路径 use super::utils::timestamp; // 从父模块 network 出发 use self::packet::Packet; // 从当前模块 protocol 出发crate::是最推荐用于业务代码的路径方式。原因很简单它只受 crate 根影响不随模块嵌套深度变化。你从src/network/protocol.rs移动到src/services/network/protocol.rscrate::config::Config这一行完全不用改但如果是use config::Config;这种依赖当前模块位置的写法一旦模块层级变了路径就断了。super::则适合在父子模块之间做局部协作。比如network/protocol.rs要访问network模块内的utils用super::utils比写一长串crate::network::utils简洁得多。这个场景里两者都合法我倾向于选更短的那个但前提是你能保证模块不会随意改位置。这里提醒一个 2018 edition 之后容易踩的坑use 语句里的相对路径规则变了。旧版可以直接写use network::tcp::connect;新版如果这么写编译器会把它当成外部 crate 去解析。正确的相对路径必须以crate、self、super之一开头。也就是说在新版里没有“裸相对路径”这种东西了。2.2 可见性谱系私有、pub、pub(crate)、pub(super) 怎么选Rust 默认的可见性是私有这个“私有”的粒度是模块不是文件。也就是说两个类型只要不在同一个模块里互相之间就不能直接访问对方的私有内容。很多新手在拆文件之后报错以为是自己代码写错了其实就是忘了加可见性修饰。完整的可见性选择可以看这张表写法含义典型场景不加修饰当前模块内可见内部实现细节pub对外完全公开公共 APIpub(crate)整个 crate 内部可见跨模块内部协作pub(super)父模块及其子模块可见父子模块紧密协作pub(in crate::path)指定模块路径内可见复杂边界的精细控制pub mod api { pub(crate) fn prepare() {} pub(super) fn configure() {} pub fn handle() {} }pub(crate)是我在项目里用得最多的一种可见性。很多内部类型、辅助函数根本不需要暴露给外部使用者但又需要让同 crate 的多个模块共享。此时pub(crate)能在编译期就拦住“对外泄漏”这件事这是团队协作时最值钱的一道边界。pub(in path)这种写法非常少见但在某些大型系统里确实有用。比如 A 模块内部有两个子模块某个中间类型只给这两个子模块用pub(crate)范围太大pub(in crate::a::internal)则精确得多。不过如果你刚接触模块系统可以暂时忽略它把这个知识点留到真正需要时再查。2.3 pub use 重导出定义模块的公共门面很多教程会把pub use解释成“省几个字母的导入写法”这话没错但格局小了。pub use真正的价值是设计模块对外的公共 API 面。设想一个没有重导出的项目使用者要创建订单得写这样的路径use my_crate::services::payment::processor::OrderProcessor;这个路径把模块内部的组织细节完全暴露了。哪天你把processor挪到core子模块里所有依赖这个路径的代码都得改。反过来如果你在 crate 入口统一重导出// src/lib.rs mod services; mod domain; pub use domain::order::{Order, OrderStatus}; pub use services::payment::OrderProcessor;外部使用者只需要写use my_crate::{Order, OrderProcessor};。内部模块树怎么调整对外 API 面都能保持稳定。这是典型的门面模式也是 rlib crate 设计公共接口时的基本素养。pub use还支持重命名pub use retry_client::RetryClient as Client;。我经常用它来隐藏实现的命名细节对外只暴露约定好的名称。这个技巧在做 SDK、维护长期稳定的公共接口时尤其有用你可以尽情调整内部实现只要重导出不变使用方就无感知。3. 现代项目中的模块组织设计思路规则掌握之后真正的难点是设计。怎么划分模块边界、怎么控制依赖方向、怎么摆放测试代码这些没有标准答案但确实有一些经过大量项目验证的通用原则。这一节给出我自己在多个项目里反复使用的一套设计方法。3.1 模块边界划分领域优先依赖单向第一个原则是“按领域划分模块”而不是“按技术类型划分”。很多初学者喜欢建utils、helpers、models这种目录结果utils里装了日期处理、字符串工具、文件读写最后变成一个大杂烩。领域优先的意思是把模块的边界画在业务概念线上。比如一个订单系统原子模块的划分不是models和services而是order、payment、user。每个业务概念内部自己负责自己的类型、行为、错误处理。这样改订单逻辑不会误碰支付代码新增员工模块也只是新增一个employee目录。第二个原则是“依赖方向保持单向”。模块之间的依赖如果画成一张有向图应该大体上是朝着一个方向流动的入口模块依赖领域模块领域模块依赖基础设施模块基础设施模块谁也不依赖。一旦出现反向依赖比如数据库模块去调用订单模块里的类型项目很快会陷入循环引用或者每次改动都要跨多个模块的窘境。依赖单向不仅是为了编译通过更是为了让模块可以独立测试、独立替换。3.2 一个分层管理系统的模块结构实例以我做过的一个模拟项目 X 为例目标是做一个内部管理系统需要提供 HTTP API、业务逻辑层、数据库访问层。最终的模块树是这样src/ ├── lib.rs ├── api/ │ ├── mod.rs │ ├── routes.rs │ └── middleware.rs ├── domain/ │ ├── mod.rs │ ├── order.rs │ ├── payment.rs │ └── user.rs ├── infrastructure/ │ ├── mod.rs │ ├── db.rs │ └── cache.rs └── support/ ├── mod.rs ├── errors.rs └── time.rsapi层只有一个任务把外部请求翻译成领域层的调用再返回合适的响应。domain层是纯业务逻辑不依赖任何 HTTP 和数据库细节。infrastructure层提供数据库和缓存的具体实现。support层放到处都要用的错误类型和时间工具。这种分层最直接的好处是依赖方向从 api 到 domain 再到 infrastructure 单向流动。domain 核心代码里没有一行 SQL没有 HTTP 状态码测试时只需要 mock 掉infrastructure的接口。实际开发里某次增加新接口时我只需要动 api 和 domain数据库层的代码完全不用碰。模块内部每个目录都用一个mod.rs统一管理子模块声明这也是旧式写法里表现不错的场景。因为目录名已经足够表达主题api/mod.rs毕竟比api.rs直观不少。不过如果你用的是同构文件方案效果也完全等价可以按自己的工具链偏好选择。3.3 测试与示例代码的摆放原则模块系统直接决定了测试怎么组织。单元测试放在被测模块内部用#[cfg(test)]标记这样测试代码只会在cargo test编译时出现不会污染生产产物。// src/domain/order.rs #[cfg(test)] mod tests { use super::*; #[test] fn order_can_be_created() { let order Order::new(ord-1, 999); assert_eq!(order.id, ord-1); } }注意这里的use super::*;它把当前模块里的类型全部引入测试子模块。这个约定在 Rust 社区几乎是通用习惯测试代码读起来也很顺。集成测试则放在tests/目录。集成测试会被当作独立的 crate 编译只能访问lib.rs中pub暴露出来的接口。这一点非常关键它倒逼你设计好公共 API。我在写集成测试时经常发现自己不得不绕很深的模块路径才能拿到某个类型那多半说明重导出设计有问题。碰到这种情况就回去调整lib.rs的pub use而不是在测试代码里硬凑。示例程序一般放examples/目录它同样以外部 crate 的身份访问lib.rs的公共接口。保持tests和examples目录干净会让你对模块边界的感知更加敏锐。4. 实操过程从零搭建模块化的订单服务前面讲了不少原则现在来一次完整的实操。我们直接动手用 1.94 版本从零搭建一个订单服务的模块化骨架。重点看文件结构、模块声明、路径和重导出业务细节比较简单但流程是完整的。4.1 环境准备与目录骨架先创建库类型的 cratecargo new orders --lib cd orders然后按分层思路创建目录mkdir -p src/api src/domain src/infrastructure src/support接着创建各个入口文件。这里采用一个折中的策略顶层模块用同构文件子模块用mod.rs。这样既能看到两种写法的混合使用也符合真实项目中渐进迁移的状态。src/ ├── lib.rs ├── api.rs ├── api/ │ ├── mod.rs │ ├── routes.rs │ └── middleware.rs ├── domain.rs ├── domain/ │ ├── mod.rs │ ├── order.rs │ └── payment.rs ├── infrastructure.rs ├── infrastructure/ │ ├── mod.rs │ ├── db.rs │ └── cache.rs ├── support.rs └── support/ ├── mod.rs ├── errors.rs └── time.rs这个骨架的好处是顶层四个模块一眼就能从文件名判断内容每个目录内部又有一个mod.rs作为子模块的入口。跳转时按下 Ctrl 点击模块名IDE 能准确定位到同构文件整体体验很顺。4.2 分层声明与实现lib.rs、api、domain、supportlib.rs是整个 crate 的大门只做组装和重导出// src/lib.rs mod api; mod domain; mod infrastructure; mod support; pub use api::routes::OrderApi; pub use domain::{order::Order, payment::Payment}; pub use infrastructure::db::DbPool;注意这里的mod声明都是私有的只有pub use的类型对外可见。外部使用者拿到手的只有订单、支付、API 网关和数据连接池这几个类型内部实现细节全部封闭。错误类型统一放在support/errors.rs// src/support/errors.rs #[derive(Debug)] pub enum AppError { NotFound(String), InvalidInput(String), Store(String), } // src/support/mod.rs pub mod errors; pub mod time; pub use errors::AppError as Error;我在support/mod.rs里做了pub use AppError as Error的重命名这样其他模块引入时只需要use crate::support::Error;语义更干净也方便以后扩展错误类型时把Error变成一个统一的包装结构。infrastructure/db.rs实现数据访问// src/infrastructure/db.rs use crate::support::Error; pub struct DbPool { conns: u32, } impl DbPool { pub fn new(conns: u32) - Self { Self { conns } } pub fn insert_order(self, order: crate::domain::order::Order) - Result(), Error { if order.amount 0 { return Err(Error::InvalidInput(order amount must be positive.into())); } Ok(()) } }这里有一个值得注意的反向依赖infrastructure层使用了domain层的Order类型依赖箭头从下指向上这在严格单向依赖里是需要警惕的。为了让这个示例保持简单我直接引用了Order但实际项目中更安全的做法是让数据库层只依赖纯值类型或者把持久化能力定义成 trait 在domain层声明、在infrastructure层实现。下一节我们会看到更彻底的优化方向。domain/order.rs定义领域模型// src/domain/order.rs use crate::infrastructure::db::DbPool; use crate::support::Error; pub struct Order { pub id: String, pub amount: i64, } impl Order { pub fn new(id: String, amount: i64) - Self { Self { id, amount } } pub fn save(self, pool: DbPool) - Result(), Error { pool.insert_order(self) } }api/routes.rs做请求到领域层的桥接// src/api/routes.rs use crate::domain::order::Order; use crate::infrastructure::db::DbPool; use crate::support::Error; pub struct OrderApi { pub pool: DbPool, } impl OrderApi { pub fn create(self, id: String, amount: i64) - ResultOrder, Error { let order Order::new(id, amount); order.save(self.pool)?; Ok(order) } }这样从OrderApi::create到Order::save再到DbPool::insert_order调用链是单向的。api 层只负责参数校验和调用具体业务规则在 domain 层数据操作在 infrastructure 层。业务逻辑和基础设施的解耦靠的就是模块边界的划分。至此在项目根目录执行cargo build应该能一次通过。如果报错优先检查模块声明、文件路径、可见性这三样。4.3 接口收敛与错误类型的模块级统一上面的骨架能跑通但还有两个可以明显优化的点这也是我在真实项目里总结出的经验。第一是错误类型的路径收敛。现在db.rs和order.rs里都直接use crate::support::Error;这没问题但如果以后错误类型改名或者移动位置所有引用都要跟着改。解决办法是在support/mod.rs里统一重导出其他模块只依赖support这一层而不是具体文件。第二是跨模块边界的数据结构。目前的Order直接被 api、domain、infrastructure 三层共用对于简单服务没问题但如果 api 层的请求体和 domain 层的领域模型结构差异很大就需要在 api 层定义 DTO在方法内部做转换。原则是跨模块边界的类型保持稳定不稳定就加一层映射。按照这两个优化修改后最终模块树不变但接口更收敛、依赖更清晰。这样一套骨架后续加新功能时只需要在对应目录新增文件并在mod.rs里补一行声明即可。5. 常见问题与排查技巧实录模块系统虽然规则明确但实际使用中还是会遇到各种奇怪的报错和 IDE 问题。这一节把我在 1.94 上实测过程中遇到的高频问题整理成速查帮你少走弯路。5.1 编译报错三步定位法遇到file not found for module或unresolved import这类错误建议按以下顺序排查别一上来就四处复制文件。第一步检查模块声明。确认在父模块里已经写了mod xxx;。没有声明编译器根本不会去找文件报错往往就是 file not found。第二步检查文件路径与模块树是否一一对应。同构文件方案下模块foo::bar对应源码根下的foo.rs和foo/bar.rs。如果foo.rs不在根而是在src/foo/mod.rs而你又写成了foo.rs路径就错位了。第三步检查可见性。文件找到了类型却用不了绝大多数是目标项或中间模块缺少pub。Rust 的报错信息里会明确写type is private或module is private跟着提示去加可见性即可。这里有一张速查表覆盖最常见的几种报错症状原因解法file not found for modulexxxmod 声明存在但文件不存在或拼写不符检查xxx.rs或xxx/mod.rs位置failed to resolve crate::yyy路径层级与模块树不一致从 lib.rs 逐层往下核对typeOrderis private目标 struct 缺少 pub给类型加pubmoduleorderis private父模块没有pub mod改为pub mod或通过pub use重导出cannot find function in this scopeuse 路径起点错误用crate::、self::、super::开头5.2 rust-analyzer 模块解析的三类坑rust-analyzer 是目前 Rust 生态最主流的 IDE 后端但它对模块系统的解析并不是无懈可击的。实测下来有三类问题比较常见。第一类是新文件未被识别。刚创建的文件如果在父模块里还没有mod声明rust-analyzer 会显示一堆红色波浪线看起来像编译错误其实编译也过不了。这个时候不用慌先补上mod声明再等 r-a 重新索引。第二类是缓存问题。在做了大量模块移动、重命名之后有时编辑器里会出现跳转失效、误报错误的情况但命令行cargo build却一切正常。这个问题的根源是 r-a 的模块缓存没刷新。解决办法是重载窗口或执行rust-analyzer: Restart server命令实测都能恢复。第三类是大小写问题。Rust 的模块名和文件名默认大小写敏感但 Windows 文件系统默认不太敏感。你在 Windows 上写mod Network;对应Network.rs本地可能正常推到 CI 的 Linux 环境就必定报错。这个坑我踩过不止一次检查时重点看文件名和模块名的每个字母是否完全一致。5.3 模块循环依赖的规避方案Rust 对模块循环引用的处理比较严格一旦模块相互引用常会出现 E0433 或莫名其妙的 unresolved import。我在项目里总结了几种有效的规避方式。第一种是检查依赖方向。新增一行use时先想清楚这个依赖把箭头指向了哪个方向。如果两个模块互相依赖多半是边界划分本身有问题。第二种是提取公共类型。两个模块都需要某个结构体那就把它下沉到support或shared模块两边都从公共层引入依赖箭头变成 A 到公共层、B 到公共层不再互相指。第三种是用 trait 解耦。反向依赖的经典场景数据库模块需要Order类型。可以把存储能力抽象成 trait 放在 domain 层infrastructure 实现 trait依赖方向就变成正向的了。// src/domain/order.rs pub trait OrderStore { fn insert(self, order: Order) - Result(), Error; } // src/infrastructure/db.rs impl crate::domain::order::OrderStore for DbPool { fn insert(self, order: Order) - Result(), Error { // 具体实现 } }第四种是重新划分边界。如果两个模块确实强耦合比如订单和订单明细强行拆成两个模块反而制造更多跨模块调用。不如合并为一个模块内部再用子模块隔离。模块的粒度不是越小越好关键是边界清晰、依赖单向。我实际见过的所谓循环依赖一多半是路径写错或者可见性没加对而不是真的存在不可逆的循环结构。先按前面的三步定位法排查再考虑重构边界大多问题都能化解。我自己在 1.94 上把这套模块化流程完整跑过一遍之后最深的感触是Rust 的模块系统一旦理解透了它对项目结构的约束力比任何团队规范都强。你不需要靠文档反复叮嘱同事“不要乱放代码”模块边界和可见性天然会逼出一个合理的结构。文件名怎么取、目录怎么建、哪些类型对外、哪些藏在内部这几件最基础的事做对了项目就会变得非常“顺手”。希望这篇能帮你在模块化的路上少踩几个坑。