使用 use 关键字将路径引入作用域

此项更改之前，外部代码必须使用路径 restaurant::front_of_house::hosting::add_to_waitlist() 调用 add_to_waitlist 函数，这还要求将 front_of_house 模块标记为 pub。现在，pub use 已从根模块重新导出 hosting 模块，外部代码就可以改用路径 restaurant::hosting::add_to_waitlist()。

当代码的内部结构与调用代码的程序员理解领域概念的方式不同时，重新导出就很有用。例如，在餐厅这个比喻中，餐厅经营者会考虑“前厅”和“后厨”，但来餐厅用餐的顾客可能不会从这些角度思考餐厅的区域。使用 pub use，我们可以按一种结构编写代码，同时公开另一种结构。这样，库内部代码的组织对库的开发者来说很清晰，而库的调用者也能方便地使用它。第 14 章的“导出便捷的公共 API”一节将展示另一个 pub use 示例，以及它对 crate 文档的影响。

使用外部包

第 2 章中，我们编写猜数字游戏项目时使用了一个名为 rand 的外部包来生成随机数。为了在项目中使用 rand，我们在 Cargo.toml 中添加了这一行：

文件名：Cargo.toml

rand = "0.10.1"

在 Cargo.toml 中将 rand 添加为依赖，会告诉 Cargo 从 crates.io 下载 rand 包及其依赖，并让我们的项目能够使用 rand。

随后，为了将 rand 中的定义引入包的作用域，我们添加了一条以 crate 名称 rand 开头的 use 语句，并列出想要引入作用域的项目。回想第 2 章“生成随机数”一节，我们将 rand::prelude 模块中的项目引入作用域，并调用了 rand::rng 函数：

use std::io;

use rand::prelude::*;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::rng().random_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Rust 社区成员已经在 crates.io 上发布了许多包。将其中任何一个引入你的包，都需要执行相同步骤：在包的 Cargo.toml 文件中列出它们，并使用 use 将 crate 中的项目引入作用域。

请注意，标准库 std 也是一个外部于我们包的 crate。由于标准库随 Rust 语言一起发布，我们不需要修改 Cargo.toml 来包含 std。但仍需要使用 use 引用它，将其中的项目引入包的作用域。例如，对于 HashMap，我们会使用下面这行代码：

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

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

使用嵌套路径简化 `use` 列表

如果要使用同一 crate 或同一模块中定义的多个项目，将每个项目分别列在单独一行，会占用文件中大量垂直空间。例如，示例 2-4 的猜数字游戏中有两条 use 语句，将 std 中的项目引入作用域：

文件名：src/main.rs

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

use rand::prelude::*;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::rng().random_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

我们可以改用嵌套路径，在一行中将相同的项目引入作用域。具体做法是先指定路径的公共部分，后跟双冒号，再用花括号括住路径中不同的部分，如示例 7-18 所示。

文件名：src/main.rs

use rand::prelude::*;
// --snip--
use std::{cmp::Ordering, io};
// --snip--

fn main() {
    println!("Guess the number!");

    let secret_number = rand::rng().random_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse().expect("Please type a number!");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

示例 7-18：指定嵌套路径，将多个具有相同前缀的项目引入作用域

在较大的程序中，使用嵌套路径从同一 crate 或模块引入多个项目，可以大幅减少单独的 use 语句数量！

路径的任意层级都可以使用嵌套路径；当两个 use 语句共享子路径时，这种做法尤其有用。例如，示例 7-19 展示了两条 use 语句：一条将 std::io 引入作用域，另一条将 std::io::Write 引入作用域。

文件名：src/lib.rs

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

示例 7-19：一条 use 语句是另一条路径的子路径

这两条路径的公共部分是 std::io，它也是第一条完整路径。要将这两条路径合并为一条 use 语句，可以在嵌套路径中使用 self，如示例 7-20 所示。

文件名：src/lib.rs

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

示例 7-20：将示例 7-19 中的路径合并到一条 use 语句中

这行代码将 std::io 和 std::io::Write 引入作用域。

使用 glob 运算符导入项目

如果想将某个路径中定义的所有公开项目引入作用域，可以在该路径后指定 * glob 运算符：

#![allow(unused)]
fn main() {
use std::collections::*;
}

这条 use 语句会将 std::collections 中定义的所有公开项目引入当前作用域。使用 glob 运算符时要谨慎！Glob 可能会让人更难判断哪些名称位于作用域内，以及程序中使用的名称定义在哪里。此外，如果依赖项更改了定义，你导入的内容也会随之改变；例如，升级依赖项时，如果它添加了与你在同一作用域中定义的名称相同的项目，就可能导致编译器错误。

测试时经常会使用 glob 运算符，将所有待测内容引入 tests 模块；我们将在第 11 章“如何编写测试”一节中讨论这一点。Glob 运算符有时也会作为预导入模式的一部分使用；更多信息请参阅标准库文档。

Rust 程序设计语言