Rust 文件组织实战案例详解本文以 rust-learning-demo 项目为贯穿全篇的实战案例，逐文件、逐行拆解 Rust 的模块系统、可见性、重导出、条件编译、测试组织、Feature 开关等核心机制。读完本文，你不仅能理解 Rust 文件组织的"规则"，更能看到这些规则在真实项目中如何落地。第一章：Crate 与 Package——从 Cargo.toml 开始1.1 Package 的概念在 Rust 世界中，每个带有Cargo.toml的目录就是一个Package（包）。Package 是 Cargo 的构建单元，定义了项目的名称、版本、依赖关系以及产出物。我们项目的Cargo.toml位于rust-learning-demo/Cargo.toml：[workspace] resolver = "2" members = [ ".", "packages/*", ] [package] name = "rust-learning-demo" version = "0.1.0" edition = "2021" default-run = "rust-learning-demo"关键字段解读：[workspace]：声明本项目是一个 Cargo Workspace（工作空间）。members = [".", "packages/*"]表示当前根目录本身和packages/下的所有子目录都是工作空间的成员包。Workspace 允许在同一个仓库中管理多个独立 Crate，它们共享同一个Cargo.lock和target/目录，实现高效的增量编译。resolver = "2"：使用新版依赖解析器（Rust 2021 edition 默认），更精确地处理 features 统一和依赖重叠。name：Package 的名称，也是发布到 crates.io 时的名称。注意这里的名字是rust-learning-demo，但这不一定是 Crate 的名字——Crate 的名字由[lib]和[[bin]]决定。edition = "2021"：指定 Rust 版本。2015 版和 2018+ 版在模块系统上有重大差异（详见后续章节），2021 是当前广泛使用的稳定版本。default-run：当运行cargo run而不指定二进制名称时，默认运行的二进制目标。1.2 Crate（箱）——编译的最小单元Crate是 Rust 编译器的核心概念，是编译的最小独立单元。一个 Package 可以包含一个库 Crate和多个二进制 Crate。Crate 分为两种：二进制 Crate（Binary Crate）：包含fn main()，编译为可执行文件。库 Crate（Library Crate）：不包含main()，编译为rlib/dylib/staticlib，供其他 Crate 引用。在这个项目中，我们同时拥有这两种 Crate：[lib] name = "rust_learning_lib" crate-type = ["staticlib", "cdylib", "rlib"] [[bin]] name = "rust-learning-demo" path = "src/main.rs" [[bin]] name = "cli" path = "src/bin/cli.rs"1.3 库 Crate 命名的陷阱[lib] name = "rust_learning_lib"这一行藏着一段重要的工程经验。为什么加_lib后缀？在 Windows 平台上，Rust 编译器会为二进制 Crate 和库 Crate 生成同名的.dll/.exe文件。如果库 Crate 叫rust_learning_demo而二进制 Crate 也叫rust_learning_demo，Windows 会因为文件重名而报错（Cargo issue #8519）。加_lib后缀是一个被广泛采用的规避方案。完整的注释在AGENTS.md中有说明：[lib] name = "rust_learning_lib" — _lib 后缀防 Windows 冲突crate-type的作用：crate-type = ["staticlib", "cdylib", "rlib"]rlib：Rust 原生静态库格式，是 Rust Crate 之间链接的默认格式。你的项目依赖其他 Rust Crate 时，它们被编译为 rlib。staticlib：C 语言兼容的静态库（.lib/.a），供其他语言调用。cdylib：C 语言兼容的动态库（.dll/.so/.dylib），供其他语言在运行时加载。对于纯 Rust 到 Rust 的项目，通常只需要rlib。这里同时生成三种类型主要是为了演示。1.5 Workspace 成员包除了根 Crate 之外，这个项目还通过[workspace]管理了 5 个独立的子包，全部在packages/目录下：包目录Crate 名类型依赖产物packages/corecorecdylib + rlib—core.dllpackages/plugin_aplugin_acdylib + rlibcoreplugin_a.dllpackages/plugin_bplugin_bcdylib + rlibcoreplugin_b.dllpackages/appappbincore, plugin_aapp.exepackages/cliclitoolbincoreclitool.exe这些子包有各自的Cargo.toml和src/目录，可以独立构建。它们通过根 Cargo.toml 中的members = [".", "packages/*"]注册到同一个 Workspace 中，共享target/构建缓存和Cargo.lock依赖锁定。Workspace 的意义在于：当项目需要产出多个可执行文件和动态库（如微服务架构、插件系统、客户端+服务端），又希望它们共享同一个仓库和依赖版本时，Workspace 是最佳选择。1.6 入口文件的铁律Rust/Cargo 对入口文件有严格的约定：文件路径作用是否必须存在src/lib.rs库 Crate 根入口有[lib]时必须有src/main.rs默认二进制入口不指定[[bin]]时有默认值src/bin/name.rs附加二进制入口可选关键认知：无论项目有多少个.rs文件，编译器每次编译时的根节点有且只有一个。对于库 Crate，根节点是lib.rs；对于默认二进制，根节点是main.rs。所有其他文件都必须从根节点通过mod声明被引入。没有任何文件会被"自动包含"。第二章：薄层 main.rs 设计模式——架构的第一道分水岭2.1 为什么 main.rs 一定要薄？打开项目中的src/main.rs：fnmain(){userust_learning_lib::prelude::*;log_info("Starting rust-learning-demo (binary crate)...");letconfig=AppConfig::load().unwrap();println!("Config loaded: {:?}",config);letresult=download_file(config.url);println!("Download result: {:?}",result);userust_learning_lib::visibility::public_function;println!("{}",public_function());}可以看到，main.rs只有约 15 行，其中没有任何业务逻辑。它只做了三件事：导入库 Crate 的功能、调用库 Crate 的 API、输出结果。为什么必须这样设计？核心原因在于：main.rs无法被其他文件引用。二进制 Crate（Binary Crate）本身不是一个可被use的模块。如果你把业务逻辑写在main.rs里，那么：src/bin/cli.rs无法复用main.rs中的逻辑集成测试无法测试main.rs中的函数示例（example）无法引用main.rs中的代码而lib.rs中的代码可以被所有二进制文件、测试、示例引用。这是 Rust 项目架构的第一条黄金法则：把逻辑放在 lib 中，把 main 做成薄薄的外壳。项目AGENTS.md也明确约定：main.rs不超过 100 行。2.2 一个 Package 多个二进制入口再看src/bin/cli.rs：userust_learning_lib::{config::settings::AppConfig,download::http::download_file,utils::log_info,};fnmain(){log_info("Starting CLI tool (bin/cli.rs)...");println!("Usage: cli [url]");leturl=std::env::args().nth(1).unwrap_or_else(||{letconfig=AppConfig::load().unwrap();config.url});letresult=download_file(url);println!("Download result: {:?}",result);}这个文件是第二个二进制入口，编译为独立的cli.exe。它展示了几个关键设计：共享库 Crate：main.rs和cli.rs都从rust_learning_lib导入功能，避免代码重复。不同的职责：main.rs展示 API 使用方式，cli.rs展示命令行参数处理。两者不同的关注点通过共享的库 Crate 得到统一。不同的导入方式：main.rs使用 prelude 批量导入，cli.rs使用显式路径精确导入。两种风格各有适用场景。运行方式：cargo run# 运行默认二进制（main.rs）cargo run--bincli# 运行附加二进制（cli.rs）cargo run--bincli--"https://custom.url"# 传参2.3 验证运行执行cargo run，控制台会输出：[INFO] Starting rust-learning-demo (binary crate)... Config loaded: AppConfig { url: "https://example.com", timeout: 30 } Download result: Ok("Downloaded content from https://example.com") I am pub — accessible from anywhere这个输出验证了：main.rs成功调用了lib.rs中的log_info函数（从 prelude 导入）通过重导出后的AppConfig和download_file正常工作visibility::public_function()作为pub级别的函数可以被二进制 Crate 访问第三章：mod 与 use——模块系统的灵魂3.1 mod 声明——加载文件的唯一方式mod关键字的本质作用是声明一个子模块。当编译器遇到mod foo;（不带代码块）时，它知道当前模块有一个名为foo的子模块，于是去硬盘查找对应的文件。看src/lib.rs中的模块声明：pubmoddomain;pubmodinfrastructure;pubmodapi;pubmodconfig;pubmoddownload;pubmodutils;pubmodvisibility;pubmodreexports;pubmodprelude;pubmodinline_demo;pubmodconditional;每一行mod声明都是一个"根须"，从lib.rs（根节点）延伸到不同的文件。没有mod声明，编译器根本不知道这些文件存在。如果删除任意一行，对应的整个模块树都会被编译器忽略。3.2 use——创建快捷方式use和mod有本质区别：mod是加载文件，use是创建路径别名。use不会导致任何文件被加载或编译——文件必须在之前已经被mod声明过了。// 等价写法：usecrate::visibility::public_function;// 绝对路径usevisibility::public_function;// 相对路径（从当前模块开始）// 批量引入：usecrate::utils::{log_info,log_error};// 重命名：usecrate::reexports::deep_module::HelperasReexportedHelper;3.3 路径规则Rust 中的路径从根节点开始，有三种形式：路径前缀含义示例crate::当前 Crate 根use crate::domain::user::User;self::当前模块use self::sub_module::fn;super::父模块use super::parent_fn;项目中的路径使用示例：在src/visibility/demo.rs中，子模块通过super引用父模块：pubfncall_crate_visible_from_demo()-'staticstr{super::crate_visible_function()// super 指向 visibility 模块}在src/download/http.rs中，子模块同样使用super引用父模块定义的错误类型：usesuper::DownloadError;最佳实践：在多级嵌套的模块中，优先使用crate::绝对路径。这样当你移动文件时，只需要修改mod声明位置，内部的路径引用不受影响。3.4 内联模块mod可以不在单独的文件中，而是直接内联在代码内。项目中src/inline_demo.rs演示了这种用法：pubfngreet_inline(name:str)-String{modhelpers{pubfnformat_greeting(name:str)-String{format!("Hello, {}!",name)}#[allow(dead_code)]pubfnformat_farewell(name:str)-String{format!("Goodbye, {}!",name)}}helpers
Rust 文件组织实战案例详解
Rust 文件组织实战案例详解本文以 rust-learning-demo 项目为贯穿全篇的实战案例，逐文件、逐行拆解 Rust 的模块系统、可见性、重导出、条件编译、测试组织、Feature 开关等核心机制。读完本文，你不仅能理解 Rust 文件组织的"规则"，更能看到这些规则在真实项目中如何落地。第一章：Crate 与 Package——从 Cargo.toml 开始1.1 Package 的概念在 Rust 世界中，每个带有Cargo.toml的目录就是一个Package（包）。Package 是 Cargo 的构建单元，定义了项目的名称、版本、依赖关系以及产出物。我们项目的Cargo.toml位于rust-learning-demo/Cargo.toml：[workspace] resolver = "2" members = [ ".", "packages/*", ] [package] name = "rust-learning-demo" version = "0.1.0" edition = "2021" default-run = "rust-learning-demo"关键字段解读：[workspace]：声明本项目是一个 Cargo Workspace（工作空间）。members = [".", "packages/*"]表示当前根目录本身和packages/下的所有子目录都是工作空间的成员包。Workspace 允许在同一个仓库中管理多个独立 Crate，它们共享同一个Cargo.lock和target/目录，实现高效的增量编译。resolver = "2"：使用新版依赖解析器（Rust 2021 edition 默认），更精确地处理 features 统一和依赖重叠。name：Package 的名称，也是发布到 crates.io 时的名称。注意这里的名字是rust-learning-demo，但这不一定是 Crate 的名字——Crate 的名字由[lib]和[[bin]]决定。edition = "2021"：指定 Rust 版本。2015 版和 2018+ 版在模块系统上有重大差异（详见后续章节），2021 是当前广泛使用的稳定版本。default-run：当运行cargo run而不指定二进制名称时，默认运行的二进制目标。1.2 Crate（箱）——编译的最小单元Crate是 Rust 编译器的核心概念，是编译的最小独立单元。一个 Package 可以包含一个库 Crate和多个二进制 Crate。Crate 分为两种：二进制 Crate（Binary Crate）：包含fn main()，编译为可执行文件。库 Crate（Library Crate）：不包含main()，编译为rlib/dylib/staticlib，供其他 Crate 引用。在这个项目中，我们同时拥有这两种 Crate：[lib] name = "rust_learning_lib" crate-type = ["staticlib", "cdylib", "rlib"] [[bin]] name = "rust-learning-demo" path = "src/main.rs" [[bin]] name = "cli" path = "src/bin/cli.rs"1.3 库 Crate 命名的陷阱[lib] name = "rust_learning_lib"这一行藏着一段重要的工程经验。为什么加_lib后缀？在 Windows 平台上，Rust 编译器会为二进制 Crate 和库 Crate 生成同名的.dll/.exe文件。如果库 Crate 叫rust_learning_demo而二进制 Crate 也叫rust_learning_demo，Windows 会因为文件重名而报错（Cargo issue #8519）。加_lib后缀是一个被广泛采用的规避方案。完整的注释在AGENTS.md中有说明：[lib] name = "rust_learning_lib" — _lib 后缀防 Windows 冲突crate-type的作用：crate-type = ["staticlib", "cdylib", "rlib"]rlib：Rust 原生静态库格式，是 Rust Crate 之间链接的默认格式。你的项目依赖其他 Rust Crate 时，它们被编译为 rlib。staticlib：C 语言兼容的静态库（.lib/.a），供其他语言调用。cdylib：C 语言兼容的动态库（.dll/.so/.dylib），供其他语言在运行时加载。对于纯 Rust 到 Rust 的项目，通常只需要rlib。这里同时生成三种类型主要是为了演示。1.5 Workspace 成员包除了根 Crate 之外，这个项目还通过[workspace]管理了 5 个独立的子包，全部在packages/目录下：包目录Crate 名类型依赖产物packages/corecorecdylib + rlib—core.dllpackages/plugin_aplugin_acdylib + rlibcoreplugin_a.dllpackages/plugin_bplugin_bcdylib + rlibcoreplugin_b.dllpackages/appappbincore, plugin_aapp.exepackages/cliclitoolbincoreclitool.exe这些子包有各自的Cargo.toml和src/目录，可以独立构建。它们通过根 Cargo.toml 中的members = [".", "packages/*"]注册到同一个 Workspace 中，共享target/构建缓存和Cargo.lock依赖锁定。Workspace 的意义在于：当项目需要产出多个可执行文件和动态库（如微服务架构、插件系统、客户端+服务端），又希望它们共享同一个仓库和依赖版本时，Workspace 是最佳选择。1.6 入口文件的铁律Rust/Cargo 对入口文件有严格的约定：文件路径作用是否必须存在src/lib.rs库 Crate 根入口有[lib]时必须有src/main.rs默认二进制入口不指定[[bin]]时有默认值src/bin/name.rs附加二进制入口可选关键认知：无论项目有多少个.rs文件，编译器每次编译时的根节点有且只有一个。对于库 Crate，根节点是lib.rs；对于默认二进制，根节点是main.rs。所有其他文件都必须从根节点通过mod声明被引入。没有任何文件会被"自动包含"。第二章：薄层 main.rs 设计模式——架构的第一道分水岭2.1 为什么 main.rs 一定要薄？打开项目中的src/main.rs：fnmain(){userust_learning_lib::prelude::*;log_info("Starting rust-learning-demo (binary crate)...");letconfig=AppConfig::load().unwrap();println!("Config loaded: {:?}",config);letresult=download_file(config.url);println!("Download result: {:?}",result);userust_learning_lib::visibility::public_function;println!("{}",public_function());}可以看到，main.rs只有约 15 行，其中没有任何业务逻辑。它只做了三件事：导入库 Crate 的功能、调用库 Crate 的 API、输出结果。为什么必须这样设计？核心原因在于：main.rs无法被其他文件引用。二进制 Crate（Binary Crate）本身不是一个可被use的模块。如果你把业务逻辑写在main.rs里，那么：src/bin/cli.rs无法复用main.rs中的逻辑集成测试无法测试main.rs中的函数示例（example）无法引用main.rs中的代码而lib.rs中的代码可以被所有二进制文件、测试、示例引用。这是 Rust 项目架构的第一条黄金法则：把逻辑放在 lib 中，把 main 做成薄薄的外壳。项目AGENTS.md也明确约定：main.rs不超过 100 行。2.2 一个 Package 多个二进制入口再看src/bin/cli.rs：userust_learning_lib::{config::settings::AppConfig,download::http::download_file,utils::log_info,};fnmain(){log_info("Starting CLI tool (bin/cli.rs)...");println!("Usage: cli [url]");leturl=std::env::args().nth(1).unwrap_or_else(||{letconfig=AppConfig::load().unwrap();config.url});letresult=download_file(url);println!("Download result: {:?}",result);}这个文件是第二个二进制入口，编译为独立的cli.exe。它展示了几个关键设计：共享库 Crate：main.rs和cli.rs都从rust_learning_lib导入功能，避免代码重复。不同的职责：main.rs展示 API 使用方式，cli.rs展示命令行参数处理。两者不同的关注点通过共享的库 Crate 得到统一。不同的导入方式：main.rs使用 prelude 批量导入，cli.rs使用显式路径精确导入。两种风格各有适用场景。运行方式：cargo run# 运行默认二进制（main.rs）cargo run--bincli# 运行附加二进制（cli.rs）cargo run--bincli--"https://custom.url"# 传参2.3 验证运行执行cargo run，控制台会输出：[INFO] Starting rust-learning-demo (binary crate)... Config loaded: AppConfig { url: "https://example.com", timeout: 30 } Download result: Ok("Downloaded content from https://example.com") I am pub — accessible from anywhere这个输出验证了：main.rs成功调用了lib.rs中的log_info函数（从 prelude 导入）通过重导出后的AppConfig和download_file正常工作visibility::public_function()作为pub级别的函数可以被二进制 Crate 访问第三章：mod 与 use——模块系统的灵魂3.1 mod 声明——加载文件的唯一方式mod关键字的本质作用是声明一个子模块。当编译器遇到mod foo;（不带代码块）时，它知道当前模块有一个名为foo的子模块，于是去硬盘查找对应的文件。看src/lib.rs中的模块声明：pubmoddomain;pubmodinfrastructure;pubmodapi;pubmodconfig;pubmoddownload;pubmodutils;pubmodvisibility;pubmodreexports;pubmodprelude;pubmodinline_demo;pubmodconditional;每一行mod声明都是一个"根须"，从lib.rs（根节点）延伸到不同的文件。没有mod声明，编译器根本不知道这些文件存在。如果删除任意一行，对应的整个模块树都会被编译器忽略。3.2 use——创建快捷方式use和mod有本质区别：mod是加载文件，use是创建路径别名。use不会导致任何文件被加载或编译——文件必须在之前已经被mod声明过了。// 等价写法：usecrate::visibility::public_function;// 绝对路径usevisibility::public_function;// 相对路径（从当前模块开始）// 批量引入：usecrate::utils::{log_info,log_error};// 重命名：usecrate::reexports::deep_module::HelperasReexportedHelper;3.3 路径规则Rust 中的路径从根节点开始，有三种形式：路径前缀含义示例crate::当前 Crate 根use crate::domain::user::User;self::当前模块use self::sub_module::fn;super::父模块use super::parent_fn;项目中的路径使用示例：在src/visibility/demo.rs中，子模块通过super引用父模块：pubfncall_crate_visible_from_demo()-'staticstr{super::crate_visible_function()// super 指向 visibility 模块}在src/download/http.rs中，子模块同样使用super引用父模块定义的错误类型：usesuper::DownloadError;最佳实践：在多级嵌套的模块中，优先使用crate::绝对路径。这样当你移动文件时，只需要修改mod声明位置，内部的路径引用不受影响。3.4 内联模块mod可以不在单独的文件中，而是直接内联在代码内。项目中src/inline_demo.rs演示了这种用法：pubfngreet_inline(name:str)-String{modhelpers{pubfnformat_greeting(name:str)-String{format!("Hello, {}!",name)}#[allow(dead_code)]pubfnformat_farewell(name:str)-String{format!("Goodbye, {}!",name)}}helpers
