Rust: Rust 模块系统与 Cargo：代码组织与项目管理

公寓（Crate）           → 一栋楼
  楼栋名（crate name）   → 楼号
  单元（Module）         → 单元门
    房间号（Function）   → 具体的房间

// 文件结构对应关系：
// src/
//   main.rs              → 公寓大堂（入口）
//   building/
//     mod.rs             → 楼栋信息
//     unit_1/
//       mod.rs           → 1 单元
//       room_501.rs      → 501 室
//       room_502.rs      → 502 室

// 在 Rust 中，通过 mod 和 pub 精确控制谁可以访问什么
mod building {
    pub mod unit_1 {
        pub fn room_501() -> &'static str {
            "501 室：Tom 的家"
        }

        fn room_502() -> &'static str {
            "502 室：私密空间"  // 默认私有，外部不可见
        }
    }
}

fn main() {
    // 通过完整路径访问
    println!("{}", building::unit_1::room_501());
    // println!("{}", building::unit_1::room_502());  // ❌ 私有函数，编译错误
}

// ============================================
// 模块嵌套、pub 可见性、路径访问
// 演示：餐厅的厨房对顾客不可见，但对服务员可见
// ============================================

// 定义餐厅模块
mod restaurant {
    // 公开的：顾客可以进入餐厅
    pub struct Menu {
        pub name: String,
        price: f64,  // 默认私有，外部不可见
    }

    impl Menu {
        // 公开的构造函数
        pub fn new(name: &str, price: f64) -> Menu {
            Menu {
                name: name.to_string(),
                price,
            }
        }

        // 公开的方法：获取价格
        pub fn get_price(&self) -> f64 {
            self.price
        }
    }

    // 公开的：顾客可以点餐
    pub fn order_food(item: &str) -> String {
        // 私有的：厨房的操作对顾客不可见
        let prepared = prepare_in_kitchen(item);
        format!("您的 {} 已准备好: {}", item, prepared)
    }

    // 私有的：厨房是顾客不能进入的
    fn prepare_in_kitchen(item: &str) -> String {
        format!("[后厨] {} 正在烹饪中...", item)
    }

    // 嵌套模块：厨房内部
    mod kitchen {
        // 私有的存储区
        pub struct Storage {
            pub items: Vec<String>,
        }

        impl Storage {
            pub fn new() -> Storage {
                Storage {
                    items: vec![
                        "蔬菜".to_string(),
                        "肉类".to_string(),
                        "调料".to_string(),
                    ],
                }
            }
        }
    }
}

fn main() {
    // 访问公开的模块成员
    let dish = restaurant::order_food("宫保鸡丁");
    println!("{}", dish);

    // 创建公开的结构体
    let menu_item = restaurant::Menu::new("宫保鸡丁", 38.0);
    println!("菜品: {}, 价格: {:.1}元", menu_item.name, menu_item.get_price());

    // 以下代码无法编译（取消注释可试）：
    // println!("厨师信息: {}", restaurant::prepare_in_kitchen("宫保鸡丁"));  // ❌ 私有函数
    // println!("价格: {}", menu_item.price);  // ❌ 私有字段
    // let storage = restaurant::kitchen::Storage::new();  // ❌ kitchen 模块是私有的
}

您的 宫保鸡丁 已准备好: [后厨] 宫保鸡丁 正在烹饪中...
菜品: 宫保鸡丁, 价格: 38.0元

// ============================================
// use 关键字引入路径、super 与 crate 相对路径
// 模拟：公司组织架构——部门→小组→员工
// ============================================

// 顶层模块：公司
mod company {
    // 工程部门
    pub mod engineering {
        pub fn team_name() -> &'static str {
            "工程部"
        }

        // 前端小组
        pub mod frontend {
            pub fn member_count() -> u32 {
                5
            }

            // 使用 super 访问父模块（engineering）
            pub fn full_info() -> String {
                format!("{} 前端小组，{}人", super::team_name(), member_count())
            }
        }

        // 后端小组
        pub mod backend {
            pub fn member_count() -> u32 {
                8
            }

            // 使用 super 访问父模块
            pub fn full_info() -> String {
                format!("{} 后端小组，{}人", super::team_name(), member_count())
            }
        }
    }

    // 市场部门
    pub mod marketing {
        pub fn team_name() -> &'static str {
            "市场部"
        }

        // 使用 crate 路径从根访问
        pub fn total_employees() -> u32 {
            // 从 crate 根开始访问
            crate::company::engineering::frontend::member_count()
            + crate::company::engineering::backend::member_count()
            + self::member_count()
        }

        fn member_count() -> u32 {
            6
        }
    }
}

// 使用 use 引入路径——简化调用
use company::engineering::frontend;
use company::engineering::backend;
use company::marketing;

fn main() {
    // 方式 1：完整路径（不推荐，写起来太长）
    println!("{}", company::engineering::frontend::full_info());

    // 方式 2：use 引入后直接调用（推荐）
    println!("{}", frontend::full_info());
    println!("{}", backend::full_info());

    // 引入 marketing 模块
    println!("市场部人数: {}", marketing::member_count());

    // 使用 crate 路径访问
    println!("公司总人数: {}", marketing::total_employees());

    // 使用 as 别名避免冲突
    use company::engineering as eng;
    println!("部门: {}", eng::team_name());
}

工程部 前端小组，5人
工程部 后端小组，8人
市场部人数: 6
公司总人数: 19
部门: 工程部

// ============================================
// 模拟 Cargo 项目结构 + 依赖管理
// 演示：lib.rs 与 main.rs 的分工、外部依赖使用
// ============================================

// 注意：这个示例演示的是 lib.rs 中的代码
// 实际的 Cargo.toml 文件内容见下方注释

// ============================================
// Cargo.toml 内容（模拟）：
// ============================================
// [package]
// name = "my-toolkit"
// version = "0.1.0"
// edition = "2021"
//
// [dependencies]
// serde = { version = "1.0", features = ["derive"] }
// serde_json = "1.0"
// chrono = "0.4"
// regex = "1.10"
//
// [dev-dependencies]
// rand = "0.8"
//
// [profile.release]
// opt-level = 3
// ============================================

// 工具模块：日期处理
pub mod date_utils {
    pub fn format_today() -> String {
        // 实际项目中会使用 chrono::Local::now()
        "2026-07-03".to_string()
    }

    pub fn is_weekend(day: &str) -> bool {
        day.ends_with("周六") || day.ends_with("周日")
    }
}

// 工具模块：字符串处理
pub mod string_utils {
    /// 验证邮箱格式（模拟正则匹配）
    pub fn validate_email(email: &str) -> bool {
        // 简化版验证：实际用 regex crate
        email.contains('@') && email.contains('.')
    }

    /// 去除非字母数字字符（模拟）
    pub fn sanitize(input: &str) -> String {
        input.chars()
            .filter(|c| c.is_alphanumeric() || *c == ' ')
            .collect()
    }
}

// 工具模块：数学计算
pub mod math_utils {
    /// 计算斐波那契数列第 n 项
    pub fn fibonacci(n: u32) -> u64 {
        match n {
            0 => 0,
            1 => 1,
            _ => fibonacci(n - 1) + fibonacci(n - 2),
        }
    }

    /// 判断是否为质数
    pub fn is_prime(n: u32) -> bool {
        if n < 2 {
            return false;
        }
        let limit = (n as f64).sqrt() as u32;
        for i in 2..=limit {
            if n % i == 0 {
                return false;
            }
        }
        true
    }
}

// 测试模块（使用 #[cfg(test)] 条件编译）
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_validate_email() {
        assert!(string_utils::validate_email("user@example.com"));
        assert!(!string_utils::validate_email("invalid"));
    }

    #[test]
    fn test_fibonacci() {
        assert_eq!(math_utils::fibonacci(0), 0);
        assert_eq!(math_utils::fibonacci(1), 1);
        assert_eq!(math_utils::fibonacci(10), 55);
    }

    #[test]
    fn test_is_prime() {
        assert!(math_utils::is_prime(17));
        assert!(!math_utils::is_prime(1));
        assert!(!math_utils::is_prime(4));
    }

    #[test]
    fn test_sanitize() {
        assert_eq!(string_utils::sanitize("hello@world!"), "hello world");
    }
}

// ============================================
// main.rs 中的代码（模拟）：
// ============================================
// use my_toolkit::{
//     date_utils,
//     string_utils,
//     math_utils,
// };
//
// fn main() {
//     println!("今天日期: {}", date_utils::format_today());
//     println!("邮箱验证: {}", string_utils::validate_email("test@example.com"));
//     println!("质数检查: {}", math_utils::is_prime(17));
// }

fn main() {
    // 演示各工具函数
    println!("=== 工具库演示 ===");

    // 日期工具
    println!("今天: {}", date_utils::format_today());
    println!("是否是周末: {}", date_utils::is_weekend("周六"));

    // 字符串工具
    println!("邮箱验证 test@example.com: {}", string_utils::validate_email("test@example.com"));
    println!("邮箱验证 invalid: {}", string_utils::validate_email("invalid"));
    println!("净化 'hello@world!': {}", string_utils::sanitize("hello@world!"));

    // 数学工具
    println!("斐波那契第10项: {}", math_utils::fibonacci(10));
    println!("17 是质数吗: {}", math_utils::is_prime(17));
    println!("4 是质数吗: {}", math_utils::is_prime(4));

    println!("=== 演示结束 ===");

    // 运行测试的说明（实际项目中使用 cargo test）
    println!("使用 `cargo test` 运行单元测试");
}

=== 工具库演示 ===
今天: 2026-07-03
是否是周末: true
邮箱验证 test@example.com: true
邮箱验证 invalid: false
净化 'hello@world!': hello world
斐波那契第10项: 55
17 是质数吗: true
4 是质数吗: false
=== 演示结束 ===
使用 `cargo test` 运行单元测试

// ============================================
// Cargo 常用命令与 workspace 多包管理
// 模拟：一个 "任务管理器" workspace 项目
// ============================================

// ============================================
// 顶层 Cargo.toml（workspace）：
// ============================================
// [workspace]
// members = [
//     "task-core",       // 核心库
//     "task-cli",        // CLI 工具
//     "task-web",        // Web 接口
// ]
//
// [workspace.package]
// version = "1.0.0"
// edition = "2021"
// ============================================

// ============================================
// task-core/Cargo.toml：
// ============================================
// [package]
// name = "task-core"
// version.workspace = true
// edition.workspace = true
//
// [dependencies]
// serde = { version = "1.0", features = ["derive"] }
// chrono = "0.4"
// ============================================

// 模拟 task-core 库的代码
pub mod task_core {
    use std::collections::HashMap;

    /// 任务优先级
    #[derive(Debug, Clone, PartialEq)]
    pub enum Priority {
        Low,
        Medium,
        High,
        Urgent,
    }

    /// 任务状态
    #[derive(Debug, Clone, PartialEq)]
    pub enum Status {
        Todo,
        InProgress,
        Done,
        Cancelled,
    }

    /// 核心任务结构体
    #[derive(Debug, Clone)]
    pub struct Task {
        pub id: u64,
        pub title: String,
        pub priority: Priority,
        pub status: Status,
        pub tags: Vec<String>,
    }

    impl Task {
        pub fn new(id: u64, title: &str, priority: Priority) -> Task {
            Task {
                id,
                title: title.to_string(),
                priority,
                status: Status::Todo,
                tags: Vec::new(),
            }
        }

        pub fn add_tag(&mut self, tag: &str) {
            self.tags.push(tag.to_string());
        }

        pub fn is_completed(&self) -> bool {
            self.status == Status::Done || self.status == Status::Cancelled
        }
    }

    /// 任务管理器
    pub struct TaskManager {
        tasks: HashMap<u64, Task>,
        next_id: u64,
    }

    impl TaskManager {
        pub fn new() -> TaskManager {
            TaskManager {
                tasks: HashMap::new(),
                next_id: 1,
            }
        }

        pub fn create_task(&mut self, title: &str, priority: Priority) -> u64 {
            let id = self.next_id;
            self.next_id += 1;
            let task = Task::new(id, title, priority);
            self.tasks.insert(id, task);
            id
        }

        pub fn get_task(&self, id: u64) -> Option<&Task> {
            self.tasks.get(&id)
        }

        pub fn complete_task(&mut self, id: u64) -> bool {
            if let Some(task) = self.tasks.get_mut(&id) {
                task.status = Status::Done;
                true
            } else {
                false
            }
        }

        pub fn list_tasks(&self) -> Vec<&Task> {
            let mut tasks: Vec<&Task> = self.tasks.values().collect();
            tasks.sort_by_key(|t| t.id);
            tasks
        }
    }
}

// ============================================
// Cargo 命令参考（注释中演示）：
// ============================================
// 常用命令：
//   cargo new project_name      -- 创建新项目
//   cargo build                 -- 编译（debug）
//   cargo build --release       -- 编译（release 优化）
//   cargo run                   -- 编译 + 运行
//   cargo check                 -- 快速检查编译错误（不生成二进制）
//   cargo test                  -- 运行测试
//   cargo test test_name        -- 运行指定测试
//   cargo bench                 -- 运行性能基准测试
//   cargo doc --open            -- 生成文档并打开
//   cargo clippy                -- 代码 lint 检查
//   cargo fmt                   -- 代码格式化
//   cargo add crate_name        -- 添加依赖
//   cargo update                -- 更新依赖
//   cargo publish               -- 发布到 crates.io
//   cargo clean                 -- 清理编译产物
//
// Workspace 命令：
//   cargo build --workspace     -- 编译 workspace 中所有包
//   cargo test -p task-core     -- 只测试指定包
//   cargo run -p task-cli       -- 运行指定包

fn main() {
    use task_core::{Priority, TaskManager};

    println!("=== 任务管理器 (模拟 Workspace 项目) ===");

    let mut manager = TaskManager::new();

    // 创建任务
    let id1 = manager.create_task("学习 Rust 智能指针", Priority::High);
    let id2 = manager.create_task("完成模块系统练习", Priority::Medium);
    let id3 = manager.create_task("修复生产环境 Bug", Priority::Urgent);

    // 列出所有任务
    println!("\n--- 所有任务 ---");
    for task in manager.list_tasks() {
        println!("#{} [{:?}] {} - {:?}", task.id, task.priority, task.title, task.status);
    }

    // 完成一个任务
    manager.complete_task(id1);
    println!("\n完成 #{} 后:", id1);
    for task in manager.list_tasks() {
        let status = if task.is_completed() { "已完成" } else { "进行中" };
        println!("#{} {} - {}", task.id, task.title, status);
    }

    // 获取单个任务
    if let Some(task) = manager.get_task(id3) {
        println!("\n紧急任务: #{} {} ({:?})", task.id, task.title, task.priority);
    }

    println!("\n=== 演示结束 ===");
    println!("项目结构: task-core (库) + task-cli (CLI) + task-web (Web)");
    println!("使用 `cargo test -p task-core` 测试核心库");
    println!("使用 `cargo doc --open` 生成文档");
}

=== 任务管理器 (模拟 Workspace 项目) ===

--- 所有任务 ---
#1 [High] 学习 Rust 智能指针 - Todo
#2 [Medium] 完成模块系统练习 - Todo
#3 [Urgent] 修复生产环境 Bug - Todo

完成 #1 后:
#1 学习 Rust 智能指针 - 已完成
#2 完成模块系统练习 - 进行中
#3 修复生产环境 Bug - 进行中

紧急任务: #3 修复生产环境 Bug (Urgent)

=== 演示结束 ===
项目结构: task-core (库) + task-cli (CLI) + task-web (Web)
使用 `cargo test -p task-core` 测试核心库
使用 `cargo doc --open` 生成文档

// ============================================
// 综合示例：模块可见性与 API 设计
// 模拟多文件项目结构（实际项目应拆分为独立文件）
// ============================================

mod math_utils {
    pub fn add(a: i32, b: i32) -> i32 { a + b }
    pub fn multiply(a: i32, b: i32) -> i32 { a * b }
    fn internal_check(val: i32) -> bool { val >= 0 }

    pub fn safe_divide(a: i32, b: i32) -> Option<i32> {
        if b == 0 { return None; }
        if !internal_check(a) || !internal_check(b) { return None; }
        Some(a / b)
    }

    pub mod constants {
        pub const PI: f64 = 3.14159265358979;
        pub const E: f64 = 2.71828182845905;
        pub const MAX_I32: i32 = i32::MAX;
    }
}

mod string_utils {
    pub fn capitalize(s: &str) -> String {
        let mut chars = s.chars();
        match chars.next() {
            None => String::new(),
            Some(first) => first.to_uppercase().collect::<String>() + chars.as_str(),
        }
    }

    pub fn truncate(s: &str, max_len: usize) -> String {
        if s.len() <= max_len { s.to_string() }
        else { format!("{}...", &s[..max_len.min(s.len())]) }
    }
}

mod user {
    pub struct User {
        pub name: String,
        age: u8,
        email: String,
    }

    impl User {
        pub fn new(name: &str, age: u8, email: &str) -> Self {
            User { name: name.to_string(), age, email: email.to_string() }
        }

        pub fn age(&self) -> u8 { self.age }

        pub fn summary(&self) -> String {
            format!("{} ({}岁, {})", self.name, self.age, self.email)
        }
    }
}

fn main() {
    use math_utils::{add, multiply, safe_divide, constants};
    use string_utils::{capitalize, truncate};
    use user::User;

    println!("=== math_utils 模块 ===");
    println!("2 + 3 = {}", add(2, 3));
    println!("4 * 5 = {}", multiply(4, 5));
    println!("10 / 3 = {:?}", safe_divide(10, 3));
    println!("10 / 0 = {:?}", safe_divide(10, 0));
    println!("PI = {:.5}, E = {:.5}", constants::PI, constants::E);

    println!("\n=== string_utils 模块 ===");
    println!("capitalize: '{}'", capitalize("rust"));
    println!("truncate: '{}'", truncate("Hello, World!", 8));

    println!("\n=== user 模块 ===");
    let alice = User::new("Alice", 30, "alice@example.com");
    println!("{}", alice.summary());
    println!("年龄: {}", alice.age());
}

=== math_utils 模块 ===
2 + 3 = 5
4 * 5 = 20
10 / 3 = Some(3)
10 / 0 = None
PI = 3.14159, E = 2.71828

=== string_utils 模块 ===
capitalize: 'Rust'
truncate: 'Hello, ...'

=== user 模块 ===
Alice (30岁, alice@example.com)
年龄: 30