引用模块树中项的路径
为了告诉 Rust 在模块树中的哪里可以找到某个项，我们使用路径，就像我们在浏览文件系统时使用路径一样。要调用函数，我们需要知道它的路径。
路径可以采用两种形式
- 绝对路径是从 Crate 根开始的完整路径；对于来自外部 Crate 的代码，绝对路径以 Crate 名称开头，而对于来自当前 Crate 的代码，它以字面量
crate开头。 - 相对路径从当前模块开始，并使用
self、super或当前模块中的标识符。
绝对路径和相对路径后面都跟着一个或多个由双冒号 (::) 分隔的标识符。
回到代码清单 7-1，假设我们要调用 add_to_waitlist 函数。这相当于问：add_to_waitlist 函数的路径是什么？代码清单 7-3 包含代码清单 7-1，其中删除了一些模块和函数。
我们将展示两种从 Crate 根中定义的新函数 eat_at_restaurant 调用 add_to_waitlist 函数的方法。这些路径是正确的，但还存在另一个问题，这将阻止此示例按原样编译。我们稍后会解释原因。
eat_at_restaurant 函数是我们库 Crate 公共 API 的一部分，因此我们使用 pub 关键字对其进行标记。在“使用 pub 关键字公开路径”部分中，我们将更详细地介绍 pub。
文件名：src/lib.rs
mod front_of_house {
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();
}代码清单 7-3：使用绝对路径和相对路径调用 add_to_waitlist 函数
我们在 eat_at_restaurant 中第一次调用 add_to_waitlist 函数时，使用的是绝对路径。add_to_waitlist 函数与 eat_at_restaurant 定义在同一个 Crate 中，这意味着我们可以使用 crate 关键字来开始一个绝对路径。然后，我们包含每个后续模块，直到我们找到 add_to_waitlist。你可以想象一个具有相同结构的文件系统：我们将指定路径 /front_of_house/hosting/add_to_waitlist 来运行 add_to_waitlist 程序；使用 crate 名称从 Crate 根开始就像在 shell 中使用 / 从文件系统根开始一样。
我们在 eat_at_restaurant 中第二次调用 add_to_waitlist 时，使用的是相对路径。路径以 front_of_house 开头，它是与 eat_at_restaurant 在模块树的同一级别定义的模块的名称。这里，等效的文件系统路径是 front_of_house/hosting/add_to_waitlist。以模块名称开头意味着路径是相对的。
选择使用相对路径还是绝对路径是根据项目做出的决定，这取决于你更有可能将项定义代码与使用该项的代码分开移动还是一起移动。例如，如果我们将 front_of_house 模块和 eat_at_restaurant 函数移动到名为 customer_experience 的模块中，则需要更新 add_to_waitlist 的绝对路径，但相对路径仍然有效。但是，如果我们将 eat_at_restaurant 函数单独移动到名为 dining 的模块中，则 add_to_waitlist 调用的绝对路径将保持不变，但需要更新相对路径。我们通常倾向于指定绝对路径，因为我们更有可能希望独立于彼此移动代码定义和项调用。
让我们尝试编译代码清单 7-3，看看为什么它还不能编译！我们得到的错误如代码清单 7-4 所示。
$ cargo build
Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: module `hosting` is private
--> src/lib.rs:9:28
|
9 | crate::front_of_house::hosting::add_to_waitlist();
| ^^^^^^^ --------------- function `add_to_waitlist` is not publicly re-exported
| |
| private module
|
note: the module `hosting` is defined here
--> src/lib.rs:2:5
|
2 | mod hosting {
| ^^^^^^^^^^^
error[E0603]: module `hosting` is private
--> src/lib.rs:12:21
|
12 | front_of_house::hosting::add_to_waitlist();
| ^^^^^^^ --------------- function `add_to_waitlist` is not publicly re-exported
| |
| private module
|
note: the module `hosting` is defined here
--> src/lib.rs:2:5
|
2 | mod hosting {
| ^^^^^^^^^^^
For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors
代码清单 7-4：构建代码清单 7-3 中的代码时的编译器错误
错误消息表明模块 hosting 是私有的。换句话说，我们有 hosting 模块和 add_to_waitlist 函数的正确路径，但 Rust 不允许我们使用它们，因为它无权访问私有部分。在 Rust 中，所有项（函数、方法、结构体、枚举、模块和常量）默认对父模块都是私有的。如果你想将函数或结构体之类的项设为私有，可以将其放在模块中。
父模块中的项不能使用子模块中的私有项，但子模块中的项可以使用其祖先模块中的项。这是因为子模块包装并隐藏了它们的实现细节，但子模块可以看到定义它们的上下文。为了继续我们的比喻，可以将隐私规则想象成餐厅的后厨：那里发生的事情对餐厅顾客来说是私有的，但办公室经理可以看到并做他们在经营的餐厅里的任何事情。
Rust 选择以这种方式使用模块系统，以便默认隐藏内部实现细节。这样，您就知道哪些内部代码可以更改而不会破坏外部代码。但是，Rust 确实允许您使用 pub 关键字将子模块代码的内部部分公开给外部祖先模块，从而使项目公开。
使用 pub 关键字公开路径
让我们回到代码清单 7-4 中的错误，该错误告诉我们 hosting 模块是私有的。我们希望父模块中的 eat_at_restaurant 函数能够访问子模块中的 add_to_waitlist 函数，因此我们使用 pub 关键字标记 hosting 模块，如代码清单 7-5 所示。
文件名：src/lib.rs
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();
}代码清单 7-5：将 hosting 模块声明为 pub 以便从 eat_at_restaurant 中使用它
不幸的是，代码清单 7-5 中的代码仍然会导致错误，如代码清单 7-6 所示。
$ 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();
| ^^^^^^^^^^^^^^^ private function
|
note: the function `add_to_waitlist` is defined here
--> src/lib.rs:3:9
|
3 | fn add_to_waitlist() {}
| ^^^^^^^^^^^^^^^^^^^^
error[E0603]: function `add_to_waitlist` is private
--> src/lib.rs:12:30
|
12 | front_of_house::hosting::add_to_waitlist();
| ^^^^^^^^^^^^^^^ private function
|
note: the function `add_to_waitlist` is defined here
--> src/lib.rs:3:9
|
3 | fn add_to_waitlist() {}
| ^^^^^^^^^^^^^^^^^^^^
For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors
代码清单 7-6：构建代码清单 7-5 中的代码时出现的编译器错误
发生了什么？在 mod hosting 前面添加 pub 关键字会使模块公开。通过此更改，如果我们可以访问 front_of_house，则可以访问 hosting。但是 hosting 的*内容*仍然是私有的；将模块公开不会使其内容公开。模块上的 pub 关键字仅允许其祖先模块中的代码引用它，而不能访问其内部代码。因为模块是容器，所以仅将模块公开并不能做太多事情；我们需要更进一步，并选择将模块中的一个或多个项目也公开。
代码清单 7-6 中的错误表明 add_to_waitlist 函数是私有的。隐私规则适用于结构体、枚举、函数和方法以及模块。
让我们还通过在其定义之前添加 pub 关键字来公开 add_to_waitlist 函数，如代码清单 7-7 所示。
文件名：src/lib.rs
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();
}代码清单 7-7：将 pub 关键字添加到 mod hosting 和 fn add_to_waitlist 允许我们从 eat_at_restaurant 调用该函数
现在代码可以编译了！要了解为什么添加 pub 关键字允许我们在 eat_at_restaurant 中使用这些路径来遵守隐私规则，让我们看一下绝对路径和相对路径。
在绝对路径中，我们从 crate 开始，它是我们 crate 模块树的根。front_of_house 模块在 crate 根中定义。虽然 front_of_house 不是公开的，但由于 eat_at_restaurant 函数与 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 标记，所以路径的其余部分有效，并且此函数调用有效！
如果您计划共享您的库 crate 以便其他项目可以使用您的代码，那么您的公共 API 就是您与 crate 用户之间的契约，它决定了他们如何与您的代码交互。围绕管理对公共 API 的更改有很多注意事项，以使人们更容易依赖您的 crate。这些注意事项超出了本书的范围；如果您对此主题感兴趣，请参阅Rust API 指南。
包含二进制文件和库的包的最佳实践
我们提到一个包可以同时包含一个 src/main.rs 二进制 crate 根和一个 src/lib.rs 库 crate 根，并且默认情况下两个 crate 都将具有包名。通常，具有这种同时包含库和二进制 crate 的模式的包在二进制 crate 中只有足够的代码来启动一个可执行文件，该可执行文件调用库 crate 中的代码。这可以让其他项目从包提供的大部分功能中受益，因为库 crate 的代码可以共享。
模块树应该在 src/lib.rs 中定义。然后，任何公共项目都可以在二进制 crate 中使用，方法是以包名开头路径。二进制 crate 成为库 crate 的用户，就像完全外部的 crate 使用库 crate 一样：它只能使用公共 API。这有助于您设计良好的 API；您不仅是作者，您还是客户！
在第 12 章中，我们将使用一个命令行程序来演示这种组织实践，该程序将包含一个二进制 crate 和一个库 crate。
使用 super 启动相对路径
我们可以通过在路径开头使用 super 来构造从父模块而不是当前模块或 crate 根开始的相对路径。这就像使用 .. 语法启动文件系统路径一样。使用 super 允许我们引用我们知道在父模块中的项目，当模块与其父模块密切相关时，这可以使重新排列模块树更容易，但父模块将来可能会移动到模块树中的其他位置。
考虑代码清单 7-8 中的代码，该代码模拟了厨师修复错误订单并亲自将其送到客户手中的情况。back_of_house 模块中定义的函数 fix_incorrect_order 通过指定以 super 开头的 deliver_order 的路径来调用父模块中定义的函数 deliver_order
文件名：src/lib.rs
fn deliver_order() {}
mod back_of_house {
fn fix_incorrect_order() {
cook_order();
super::deliver_order();
}
fn cook_order() {}
}代码清单 7-8：使用以 super 开头的相对路径调用函数
fix_incorrect_order 函数位于 back_of_house 模块中，因此我们可以使用 super 转到 back_of_house 的父模块，在本例中是 crate，即根。然后，我们从中查找 deliver_order 并找到它。成功！我们认为 back_of_house 模块和 deliver_order 函数很可能保持彼此之间的关系，并且如果我们决定重新组织 crate 的模块树，它们将一起移动。因此，我们使用了 super，因此如果此代码被移动到不同的模块，我们将减少将来需要更新代码的地方。
公开结构体和枚举
我们也可以使用 pub 将结构体和枚举指定为公共的，但是 pub 与结构体和枚举一起使用还有一些额外的细节。如果我们在结构体定义之前使用 pub，我们会将结构体公开，但结构体的字段仍然是私有的。我们可以根据具体情况将每个字段设为公开或不公开。在代码清单 7-9 中，我们定义了一个公共的 back_of_house::Breakfast 结构体，它有一个公共的 toast 字段和一个私有的 seasonal_fruit 字段。这模拟了餐厅中顾客可以选择餐点面包类型的情况，但厨师会根据当季和库存情况决定搭配餐点的水果。可用的水果变化很快，因此顾客无法选择水果，甚至无法看到他们会得到哪种水果。
文件名：src/lib.rs
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");
}代码清单 7-9：具有一些公共字段和一些私有字段的结构体
因为 back_of_house::Breakfast 结构体中的 toast 字段是公共的，所以在 eat_at_restaurant 中我们可以使用点符号对 toast 字段进行读写。请注意，我们不能在 eat_at_restaurant 中使用 seasonal_fruit 字段，因为 seasonal_fruit 是私有的。尝试取消注释修改 seasonal_fruit 字段值的代码行，看看您会收到什么错误！
另外，请注意，因为 back_of_house::Breakfast 有一个私有字段，所以该结构体需要提供一个公共的关联函数来构造 Breakfast 的实例（我们在这里将其命名为 summer）。如果 Breakfast 没有这样的函数，我们就无法在 eat_at_restaurant 中创建 Breakfast 的实例，因为我们无法在 eat_at_restaurant 中设置私有 seasonal_fruit 字段的值。
相反，如果我们将枚举设为公共的，则其所有变体都将是公共的。我们只需要在 enum 关键字之前使用 pub，如代码清单 7-10 所示。
文件名：src/lib.rs
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;
}代码清单 7-10：将枚举指定为公共的会使其所有变体都公开
因为我们将 Appetizer 枚举设为公共的，所以我们可以在 eat_at_restaurant 中使用 Soup 和 Salad 变体。
除非枚举的变体是公共的，否则枚举就不是很有用；如果必须在每种情况下都使用 pub 注释所有枚举变体，那将很烦人，因此枚举变体的默认设置是公共的。结构体通常在字段不公开的情况下也很有用，因此结构体字段遵循默认情况下所有内容都是私有的规则，除非使用 pub 注释。
还有一种涉及 pub 的情况我们还没有介绍，那就是我们最后一个模块系统功能：use 关键字。我们将首先单独介绍 use，然后我们将展示如何组合 pub 和 use。