第一章：Rust项目结构设计——模块系统深度解析、Cargo工作空间、lib与bin分离、模块可见性控制

说实话，很多Rust初学者甚至有一定经验的开发者，都会在项目结构上栽跟头。我记得刚用Rust做第一个中型项目时，把所有代码塞进一个main.rs里，结果两周后我自己都看不懂了。嗯，这其实不是Rust的问题，而是我们对「项目结构设计」这件事重视不够。

今天我们就来聊聊，一个真正能落地的Rust项目，应该怎么搭骨架。

1.1 模块系统：Rust的代码组织哲学

Rust的模块系统，说白了就是一套「文件即模块」的映射规则。你不需要像Java那样写一堆package声明，也不用像C++那样手动管理头文件。Rust的模块路径，直接对应文件系统路径。

举个例子：

// 在 src/lib.rs 中声明
pub mod network;
pub mod storage;

// 那么你的目录结构应该是：
// src/
//   lib.rs
//   network.rs
//   storage.rs

我个人习惯把模块声明放在lib.rs里，而不是main.rs。为什么？因为lib.rs是库的入口，main.rs是二进制入口。后面我们会详细讲lib与bin分离的好处。

1.2 Cargo工作空间：多包项目的终极方案

当你的项目需要拆分成多个独立的crate时（比如一个核心库、一个CLI工具、一个Web服务），Cargo工作空间就是你的救星。

我在项目中遇到过这样的场景：一个微服务架构，每个服务都是一个独立的crate，但它们共享同一个数据模型和工具函数。如果每个服务都复制一份代码，那维护起来就是噩梦。

工作空间的配置很简单：

// 根目录下的 Cargo.toml
[workspace]
members = [
    "core",
    "cli",
    "web-server",
]

// 每个子目录都有自己的 Cargo.toml
// core/Cargo.toml
[package]
name = "my-core"
version = "0.1.0"

// cli/Cargo.toml
[package]
name = "my-cli"
version = "0.1.0"
[dependencies]
my-core = { path = "../core" }

你想想看，这样每个crate可以独立编译、独立测试、独立发布。而且工作空间内的依赖会被统一解析，不会出现版本冲突。

1.3 lib与bin分离：为什么这是最佳实践？

很多新手喜欢把所有逻辑写在main.rs里。但这样做有几个问题：

• main.rs无法被其他crate引用
• 测试代码只能写在main.rs内部，无法单独测试库逻辑
• 代码复用性极差

正确的做法是：

// src/lib.rs - 所有业务逻辑放在这里
pub fn process_data(input: &str) -> String {
    format!("Processed: {}", input)
}

// src/main.rs - 只负责启动和参数解析
use my_project::process_data;

fn main() {
    let args: Vec<String> = std::env::args().collect();
    if args.len() > 1 {
        println!("{}", process_data(&args[1]));
    }
}

我曾经接手过一个项目，main.rs有800多行，里面混杂着HTTP服务器、数据库连接、业务逻辑。重构时我花了整整一周才把它拆成lib+bin的结构。嗯，从那以后我再也不写「胖main」了。

1.4 模块可见性控制：该公开的公开，该隐藏的隐藏

Rust的可见性控制，说白了就是「谁可以看我的代码」。默认情况下，Rust中的所有项（函数、结构体、模块）都是私有的。只有显式加上pub关键字，才能被外部访问。

但这里有个细节：

// src/lib.rs
mod internal {
    pub fn helper() {
        // 这个函数虽然是pub的，但模块internal是私有的
        // 所以外部无法访问 helper()
    }
}

pub mod api {
    pub fn do_something() {
        // 这个函数可以被外部访问
    }
    
    fn private_helper() {
        // 这个函数只能在api模块内部使用
    }
}

你可能会问：「为什么要有这么复杂的可见性控制？」

我举个例子：你在做一个数据库连接池库。对外暴露的API只有Pool::new()和Pool::get_connection()。但内部有几十个辅助函数，比如recycle_connection()、check_health()。这些内部函数如果暴露出去，用户可能会误用，导致连接池崩溃。

所以，我的建议是：

• 默认全部私有
• 只有需要被外部调用的才加pub
• 使用pub(crate)让同一crate内的其他模块可以访问，但外部不行
• 使用pub(super)只允许父模块访问

1.5 知识体系总览

下面这张图，是我自己总结的Rust项目结构设计核心逻辑。你可以把它当作一个检查清单：

1.6 实战建议：从小项目到大项目的演进路径

如果你刚开始一个Rust项目，我建议你按这个顺序来：

1. 单文件阶段：先写一个main.rs，快速验证想法。但一旦超过100行，立刻拆。
2. lib+bin阶段：把核心逻辑移到lib.rs，main.rs只保留入口。
3. 多模块阶段：按功能拆分成多个模块文件，用mod声明。
4. 工作空间阶段：当项目需要多个独立crate时，引入Cargo工作空间。

我个人习惯在项目第一天就创建lib.rs。哪怕里面只有一行代码，也比以后重构要轻松得多。你想想看，代码结构就像房子的地基，地基歪了，后面装修得再好也白搭。

---