rust 包模块组织结构

一个包（package）可以拥有多个二进制单元包及一个可选的库单元包。随着包内代码规模的增长，你还可以将代码拆分到独立的单元包（crate）中，并将它作为外部依赖进行引用。

RUST提供了一系列的功能来帮助我们管理代码，包括决定哪些细节是暴露的、哪些细节是私有的，以及不同的作用域的命名管理。这些功能有时被统称为模块系统（module system），它们包括：

• 包（package）：一个用于构建、测试并分享单元包的Cargo功能
• 单元包（crate）：一个用于生成库或可执行文件的树形模块结构
• 模块（module）及use关键字：它们被用于控制文件结构、作用域及路径的私有性
• 路径（path）：一种用于命名条目的方法，这些条目包括结构体、函数和模块等

有几条规则决定了包可以包含哪些东西：首先，一个包中最多只能拥有一个库单元包。其次，包可以拥有多个二进制单元包。最后，包内必须存在至少一个单元包（库单元包或二进制单元包）。

cargo new my-project

当我们执行这条命令时，Cargo会生成一个包并创建相应的Cargo.toml文件。Cargo会默认将src/main.rs视作一个二进制单元包的根节点，这个二进制单元包与包拥有相同的名字。同样地，假设包的目录中包含文件src/lib.rs，Cargo也会自动将其视作与包同名的库单元包的根节点。

最初生产的包只包含源文件src/main.rs，这也意味着只包含一个名为my-project的二进制单元包。而假设包中同时存在src/main.rs及src/lib.rs，那么其中就会分别存在一个二进制单元包和一个库单元包，它们用于与包相同的名字。我们可以在路径src/bin下添加源文件来创建出更多的二进制单元包，这个路径下的每个源文件都会被视作单独的二进制单元包。

我们依赖的外部包，比如提供生成随机数功能的rand包就属于单元包。将单元包的功能保留在它们自己的作用域中有助于指明某个特定功能来源于哪个单元包，并避免可能得命名冲突。

定义模块来控制作用域及私有性

通过下面的方式创建一个库单元包，RUST也默认生成了单元测试的代码

cargo new --lib restaurant

// src/lib.rs
mod front_of_house {
    mod host {
        fn add_to_waitlist() {}
        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}
        fn serve_order() {}
        fn take_payment() {}
    }
}

通过mod关键字开头来定义一个模块，接着指明这个模块的名称，并在其后使用一对花括号来包裹模块体。模块内可以定义其他模块，同样也可以包含其它条目的定义，比如结构体、枚举、常量等。

我们前面提到过，src/main.rs与src/lib.rs被称为单元包的根节点，因为这两个文件的内容各自组成了一个名为crate的模块，并位于单元包模块结构的根部。这个模块结构也被称为模块树（module tree），整个模块树都被放置在一个名为crate的隐式根模块下：

crate
 └── front_of_house     
    ├── hosting     
    │   ├── add_to_waitlist     
    │   └── seat_at_table     
    └── serving     
        ├── take_order     
        ├── serve_order     
        └── take_payment

为了在RUST模块树中找到某个条目，我们需要指定条目的路径，有两种形式：

• 使用单元包或字面量crate从根节点开始的绝对路径
• 使用slef、super或内部标识符从当前模块开始的相对路径

绝对路径与相对路径都至少由一个标识符组成，标识符之间使用双冒号（::）分隔。

// src/lib.rs
pub fn eat_at_restaurant() {
    // 绝对路径
    crate::front_of_house::host::add_to_waitlist();

    // 相对路径
    front_of_house::host::add_to_waitlist();
}

我们使用绝对路径和相对路径来调用add_to_waitlist函数，大部分开发者更倾向使用绝对路径，因为我们往往会彼此独立地移动代码的定义与代码调用。

这段代码编译器报错，因为模块host是私有的。模块不仅仅被用于组织代码，同时还定义了RUST的私有边界（privacy boundary）：外部代码无法访问那些由私有边界封装的细节。

RUST中的所有条目（函数、方法、结构体、枚举、模块及常量）默认都是私有的。处于父模块中的条目无法使用子模块中的私有条目，但子模块中的条目可以使用祖先模块中的条目。虽然子模块包装并隐藏了自身的实现细节，但它却依然能够感知当前定义环境的上下文。