模块

     查看 Cargo.toml 的内容，却会发现并没有提到 src/main.rs

因为 Cargo 遵循的一个约定：

• src/main.rs : 就是一个与 包同名 的 二进制 crate 的 crate 根
• 如果包目录中包含 src/lib.rs ，则包带有与其 同名 的 库 crate ，且 src/lib.rs 是 crate 根
• crate 根文件将由 Cargo 传递给 rustc 来实际构建库或者二进制项目

     至此，已经有了一个只包含 src/main.rs 的包，意味着它只含有一个名为 my-project 的二进制 crate

     如果一个包同时含有 src/main.rs 和 src/lib.rs，则它有两个 crate：一个库和一个二进制项，且名字都与包相同

通过将文件放在 src/bin 目录下，一个包可以 拥有多个二进制 crate ：每个 src/bin 下的文件都会被编译成一个独立的二进制 crate

一个 crate 会将一个作用域内的相关功能分组到一起，使得该功能可以很方便地在 多个项目之间共享

举一个例子，曾经使用的 rand crate 提供了生成随机数的功能

通过将 rand crate 加入到我们项目的作用域中，就可以在自己的项目中使用该功能

rand crate 提供的所有功能都可以通过该 crate 的名字：rand 进行访问

将一个 crate 的功能保持在其自身的作用域中，可以知晓一些特定的功能是在自己的 crate 中定义的还是在 rand crate 中定义的，这可以 防止潜在的冲突

     例如，rand crate 提供了一个名为 Rng 的特性（trait），还可以在自己的 crate 中定义一个名为 Rng 的 struct

     因为一个 crate 的功能是在自身的作用域进行命名的，所以编译器会知道：
	 Rng 这个名字指向的是我们自己定义的 struct Rng
	 rand::Rng 这一方式指向的才是 rand crate 中的 Rng 特性

在前面提到了， src/main.rs 和 src/lib.rs 叫做 crate 根 。之所以这样叫它们的原因是：这两个文件的内容都是一个从名为 crate 的模块作为 根的 crate 模块结构 ，称为 模块树 ：

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

• 这个树展示了一些模块是如何被嵌入到另一个模块的：例如，hosting 嵌套在 front_of_house 中
• 这个树还展示了一些模块是互为 兄弟 的，这意味着它们定义在同一模块中：hosting 和 serving 被一起定义在 front_of_house 中
• 如果一个模块 A 被包含在模块 B 中，将模块 A 称为模块 B 的 子 ，模块 B 则是模块 A 的 父
  • 注意：整个模块树都植根于名为 crate 的 隐式模块 下

     这个模块树可能会令你想起电脑上文件系统的目录树：这是一个非常恰当的比喻！

     就像文件系统的目录，可以使用模块来组织代码，并且，就像目录中的文件，需要一种方法来找到模块

回头看一下前面示例的错误，这次使用 pub 关键字来标记 hosting 模块，如下面所示：

mod front_of_house {
    pub mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

不幸的是，上面的代码编译仍然有错误：

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: function `add_to_waitlist` is private
 --> src/lib.rs:9:37
  |
9 |     crate::front_of_house::hosting::add_to_waitlist();
  |                                     ^^^^^^^^^^^^^^^

error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:12:30
   |
12 |     front_of_house::hosting::add_to_waitlist();
   |                              ^^^^^^^^^^^^^^^

     在 mod hosting 前添加了 pub 关键字，使其变成公有的

     伴随着这种变化，如果可以访问 front_of_house，那也可以访问 hosting

     但是 hosting 的内容仍然是私有的；这表明使模块公有并不使其内容也是公有的

     模块上的 pub 关键字只允许其父模块引用它，因此私有性规则不但应用于模块，还应用于结构体、枚举、函数和方法

继续将 pub 关键字放置在 add_to_waitlist 函数的定义之前，使其变成公有：

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

现在代码可以编译通过了！

回头看下绝对路径和相对路径，并根据私有性规则，再检查一下为什么增加 pub 关键字使得可以在 add_to_waitlist 中调用这些路径

在绝对路径，从 crate，也就是 crate 根开始：
然后 crate 根中定义了 front_of_house 模块：front_of_house 模块不是公有的，不过因为 eat_at_restaurant 函数与 front_of_house 定义于同一模块中，使得可以从 eat_at_restaurant 中引用 front_of_house
接下来是使用 pub 标记的 hosting 模块。可以访问 hosting 的父模块，所以可以访问 hosting
最后，add_to_waitlist 函数被标记为 pub ，可以访问其父模块，所以这个函数调用是有效的！


在相对路径，其逻辑与绝对路径相同，除了第一步：不同于从 crate 根开始，路径从 front_of_house 开始
front_of_house 模块与 eat_at_restaurant 定义于同一模块，所以从 eat_at_restaurant 中开始定义的该模块相对路径是有效的
接下来因为 hosting 和 add_to_waitlist 被标记为 pub，路径其余的部分也是有效的，因此函数调用也是有效的！

还可以使用 super 开头来构建从父模块开始的相对路径。这么做类似于文件系统中以 .. 开头的语法

考虑一下下面示例的代码，它模拟了厨师更正了一个错误订单，并亲自将其提供给客户的情况。fix_incorrect_order 函数通过指定的 super 起始的 server_order 路径，来调用 server_order 函数：

fn serve_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::serve_order();
    }

    fn cook_order() {}
}

fix_incorrect_order 函数在 back_of_house 模块中，所以可以使用 super 进入 back_of_house 父模块，也就是本例中的 crate 根，在这里可以找到 serve_order

这里我们认为 back_of_house 模块和 server_order 函数之间可能具有某种关联关系，并且，如果要重新组织这个 crate 的模块树，需要一起移动它们

因此，使用 super，这样一来，如果这些代码被移动到了其他模块，只需要更新很少的代码

以使用 pub 来设计 公有 的 结构体 和 枚举 ，需要注意：

• 如果在一个结构体定义的前面使用了 pub ，这个结构体会变成公有的，但是这个 结构体的字段仍然是私有的 ：可以根据情况决定每个字段是否公有

     在下面模拟的情况是：在一家餐馆中，顾客可以选择随餐附赠的面包类型，但是厨师会根据季节和库存情况来决定随餐搭配的水果

     因为餐馆可用的水果变化是很快的，所以顾客不能选择水果，甚至无法看到他们将会得到什么水果

这里定义了一个 公有结构体 back_of_house:Breakfast，其中有一个 公有字段 toast 和 私有字段 seasonal_fruit :

mod back_of_house {
    pub struct Breakfast {
        pub toast: String,
        seasonal_fruit: String,
    }

    impl Breakfast {
        pub fn summer(toast: &str) -> Breakfast {
            Breakfast {
                toast: String::from(toast),
                seasonal_fruit: String::from("peaches"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // Order a breakfast in the summer with Rye toast
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // Change our mind about what bread we'd like
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // The next line won't compile if we uncomment it; we're not allowed
    // to see or modify the seasonal fruit that comes with the meal
    // meal.seasonal_fruit = String::from("blueberries");
}

• 因为 back_of_house::Breakfast 结构体的 toast 字段是公有的，所以可以在 eat_at_restaurant 中使用点号来随意的读写 toast 字段
• 不能在 eat_at_restaurant 中使用 seasonal_fruit 字段，因为 seasonal_fruit 是私有的

尝试去除那一行修改 seasonal_fruit 字段值的代码的注释，就会得到下面的报错：

error[E0616]: field `seasonal_fruit` of struct `back_of_house::Breakfast` is private
  --> src/lib.rs:27:5
   |
27 |     meal.seasonal_fruit = String::from("blueberries");
   |     ^^^^^^^^^^^^^^^^^^^

还请注意一点：因为 back_of_house::Breakfast 具有私有字段，所以这个结构体需要提供一个 公共的 关联函数 来 构造 示例 Breakfast ：这里命名为 summer

     如果 Breakfast 没有这样的函数，将无法在 eat_at_restaurant 中创建 Breakfast 实例，因为不能在 eat_at_restaurant 中设置私有字段 seasonal_fruit 的值

与之相反：如果将 枚举 设为 公有 ，则它的 所有成员都将变为公有 ，只需要在 enum 关键字前面加上 pub ：

     结构体通常使用时，不必将它们的字段公有化，因此结构体遵循常规，内容全部是私有的，除非使用 pub 关键字

     如果枚举成员不是公有的，那么枚举会显得用处不大；给枚举的所有成员挨个添加 pub 是很令人恼火的，因此枚举成员默认就是公有的

下面创建了名为 Appetizer 的 公有 枚举，就可以在 eat_at_restaurant 中使用 Soup 和 Salad 成员：

mod back_of_house {
    pub enum Appetizer {
        Soup,
        Salad,
    }
}

pub fn eat_at_restaurant() {
    let order1 = back_of_house::Appetizer::Soup;
    let order2 = back_of_house::Appetizer::Salad;
}

     还有一种使用 pub 的场景还没有涉及到，那就是最后要讲的模块功能：use 关键字

     将先单独介绍 use，然后展示如何结合使用 pub 和 use

     可能会比较疑惑，为什么是指定 use crate::front_of_house::hosting ，然后在 eat_at_restaurant 中调用 hosting::add_to_waitlist ，而不是通过指定一直到 add_to_waitlist 函数的 use 路径来得到相同的结果？

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting::add_to_waitlist;

pub fn eat_at_restaurant() {
    add_to_waitlist();
    add_to_waitlist();
    add_to_waitlist();
}

     虽然上面示例也完成了相同的任务，但这样的代码不清楚 add_to_waitlist 究竟是在哪里被定义的

     相比较而言，而在前面实例中，如果想使用 use 将函数的父模块引入作用域，必须在调用函数时指定父模块，这样可以清晰地表明函数不是在本地定义的，同时使完整路径的重复度最小化

另一方面，使用 use 引入 结构体 、 枚举 和 其他项 时，习惯是指定它们的 完整路径 。下面展示了将 HashMap 结构体引入二进制 crate 作用域的习惯用法：

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}

     这种习惯用法背后没有什么硬性要求：它只是一种惯例，人们已经习惯了以这种方式阅读和编写 Rust 代码

这个习惯用法有一个例外，那就是想使用 use 语句将 两个具有相同名称的项 带入作用域，因为 Rust 不允许这样做。下面展示了如何将两个具有相同名称但不同父模块的 Result 类型引入作用域，以及如何引用它们：

use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --snip--
}

fn function2() -> io::Result<()> {
    // --snip--
}

     如你所见，使用父模块可以区分这两个 Result 类型

     如果指定 use std::fmt::Result 和 use std::io::Result，将在同一作用域拥有了两个 Result 类型，当使用 Result 时，Rust 则不知道我们要用的是哪个

当使用 use 关键字将名称导入作用域时，在 新作用域 中 这个名称 是 私有的 。可以结合 pub 和 use ，这样做将项引入作用域并同时使其可 供其他代码引入自己的作用域 ，这被称为 重导出

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
}

• 通过 pub use，现在可以通过新路径 hosting::add_to_waitlist 来调用 add_to_waitlist 函数
• 如果没有指定 pub use: eat_at_restaurant 函数可以在其作用域中调用 hosting::add_to_waitlist，但外部代码则不允许使用这个新路径

     当你的代码的内部结构与调用你的代码的程序员的思考领域不同时，重导出会很有用

     例如，在这个餐馆的比喻中，经营餐馆的人会想到“前台”和“后台”，但顾客在光顾一家餐馆时，可能不会以这些术语来考虑餐馆的各个部分

     使用 pub use，可以使用一种结构编写代码，却将不同的结构形式暴露出来。这样做使我们的库井井有条，方便开发这个库的程序员和调用这个库的程序员之间组织起来

前面的猜猜看游戏。那个项目使用了一个外部包， rand 来生成随机数。为了在项目中使用 rand，在 Cargo.toml 中加入了如下行：

[dependencies]
rand = "0.5.5"

     在 Cargo.toml 中加入 rand 依赖告诉了 Cargo 要从 crates.io 下载 rand 和其依赖，并使其可在项目代码中使用

为了将 rand 定义引入项目包的作用域，加入一行 use 起始的包名，它以 rand 包名 开头并列出了需要 引入作用域的项 ：

use rand::Rng;

fn main() {
    let secret_number = rand::thread_rng().gen_range(1, 101);
}

crates.io 上有很多 Rust 社区成员发布的包，将其引入你自己的项目都需要一道相同的步骤：在 Cargo.toml 列出它们并通过 use 将其中定义的项引入项目包的作用域中

注意： 标准库 std 对于你的包来说也是 外部 crate。因为标准库随 Rust 语言一同分发，无需修改 Cargo.toml 来引入 std，不过需要通过 use 将标准库中定义的项引入项目包的作用域中来引用它们，比如使用的 HashMap：

use std::collections::HashMap;

这是一个以标准库 crate 名 std 开头的绝对路径

当需要引入很多定义于 相同包 或 相同模块 的项时，为每一项单独列出一行会占用源码很大的空间。例如：

use std::cmp::Ordering;
use std::io;
// ---snip---

可以使用 嵌套 路径将相同的项在一行中引入作用域。这么做需要指定 路径的相同部分 ，接着是 两个冒号 ，接着是 大括号 中的各自 不同的路径部分 ，如下所示：

use std::{cmp::Ordering, io};

     在较大的程序中，使用嵌套路径从相同包或模块中引入很多项，可以显著减少所需的独立 use 语句的数量！

可以在路径的任何层级使用嵌套路径，这在 组合 两个 共享子路径 的 use 语句时非常有用。例如，下面展示了两个 use 语句：一个将 std::io 引入作用域，另一个将 std::io::Write 引入作用域：

use std::io;
use std::io::Write;

两个路径的相同部分是 std::io ，这正是第一个路径。为了在一行 use 语句中引入这两个路径，可以在嵌套路径中使用 self :

use std::io::{self, Write};

这便将 std::io 和 std::io::Write 同时引入作用域

如果希望将一个路径下 所有 公有项 引入作用域，可以指定路径后跟 * 运算符：

use std::collections::*;

这个 use 语句将 std::collections 中定义的所有公有项引入当前作用域

使用 glob 运算符时请多加小心：它会使得难以推导作用域中有什么名称和它们是在何处定义的

glob 运算符经常用于测试模块 tests 中，这时会将所有内容引入作用域，有时也用于 prelude 模式