5.1 模块与可见性

Rust 的模块系统用于组织代码，使其更具结构性、可维护性和可重用性。通过模块，你可以将相关的函数、结构体、枚举和 trait 分组，并控制哪些部分对外公开，哪些保持内部私有。

定义模块

使用 mod 关键字定义一个模块。模块可以在同一个文件中内联定义，也可以对应到单独的文件或目录。

例如，在单个文件中定义模块：

mod network {
    fn connect() {
        println!("Connecting...");
    }
}

fn main() {
    // network::connect(); // 错误：connect 是私有的
}

默认情况下，模块内的所有项（函数、结构体等）都是私有的，只能在该模块内部访问。

可见性控制：pub 关键字

要使模块中的项对外可见，需使用 pub 关键字：

mod network {
    pub fn connect() {
        println!("Connecting...");
    }
}

fn main() {
    network::connect(); // 正确：connect 是公有的
}

同样，模块本身也可以是公有的：

pub mod network {
    pub fn connect() { /* ... */ }
}

这样，其他 crate 或父模块就可以访问 network 模块及其公有项。

模块的文件组织

对于较大的项目，通常将模块拆分到多个文件中。Rust 遵循约定：

• mod 名称; 会自动查找同名的 .rs 文件或 名称/ 目录。
• 项目入口（如 main.rs 或 lib.rs）是根模块。

例如，创建 src/network.rs：

// src/network.rs
pub fn connect() {
    println!("Connecting from file...");
}

然后在 src/main.rs 中声明：

// src/main.rs
mod network; // 告诉 Rust 从 network.rs 加载模块

fn main() {
    network::connect();
}

如果模块包含子模块，可以创建 network/ 目录，并在其中放置 mod.rs 或直接使用子模块文件名（如 tcp.rs、udp.rs），再在 network/mod.rs 中声明它们。

私有性规则总结

• 默认所有项都是私有的。
• 子模块可以访问父模块的私有项。
• 父模块不能直接访问子模块的私有项，除非通过公有接口。
• pub 使项在其定义模块之外可见，但调用者仍需通过完整路径或 use 引入。

小结

模块和可见性机制是 Rust 代码组织的核心。通过 mod 划分逻辑单元，通过 pub 精细控制接口暴露，既保证了封装性，又支持灵活的代码复用。理解这些规则，是构建清晰、安全且可扩展 Rust 项目的基础。