标签：use Crate crate pub 模块 house Rust mod

目录

• 包和 Crate
• 定义模块来控制作用域与私有性
  • 在模块中对相关代码进行分组
• 引用模块项目的路径
  • 使用 pub 关键字暴露路径
• 二进制和库 crate 包的最佳实践
  • super 开始的相对路径
  • 创建公有的结构体和枚举
• 使用 use 关键字将路径引入作用域
  • 创建惯用的 use 路径.
    • 使用 use 引入函数
    • 使用 use 引入结构体、枚举和其他项
    • 使用 use 的例外用法
  • 使用 as 关键字提供新的名称
  • 使用 pub use 重导出名称
  • 使用外部包
  • 嵌套路径来消除大量的 use 行
  • 通过 glob 运算符将所有的公有定义引入作用域
• 将模块拆分成多个文件
  • 另一种文件路径

本文在原文有删减，原文参考使用包、Crate 和模块管理不断增长的项目。

Rust 有许多功能可以管理代码的组织，包括：

• 包（Packages）：Cargo 的一个功能，它允许你构建、测试和分享 crate。
• Crates：一个模块的树形结构，它形成了库或二进制项目。
• 模块（Modules）和 use：允许你控制作用域和路径的私有性。
• 路径（path）：一个命名例如结构体、函数或模块等项的方式。

包和 Crate

crate 是 Rust 在编译时最小的代码单位，crate 有两种形式：二进制项和库。

二进制项 可以被编译为可执行程序，比如一个命令行程序或者一个服务器，必须有一个 main 函数来定义当程序被执行的时候所需要做的事情。

库 没有 main 函数，也不会编译为可执行程序，提供一些诸如函数之类的东西给其他项目使用。

crate root 是一个源文件，Rust 编译器以它为起始点，并构成 crate 的根模块。

包（package）是提供一系列功能的一个或者多个 crate，一个包会包含一个 Cargo.toml 文件阐述如何去构建这些 crate。

包中可以包含至多一个库 crate(library crate)，包中可以包含任意多个二进制 crate(binary crate)，但是必须至少包含一个 crate（无论是库的还是二进制的）。

输入命令 cargo new 创建包：

$ cargo new my-project
     Created binary (application) `my-project` package
$ ls my-project
Cargo.toml
src
$ ls my-project/src
main.rs

注：ls 命令为 Linux 平台的指令，Windows 下可用 dir。

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。

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

下面介绍模块、路径、use关键词和pub关键词如何在编译器中工作，以及大部分开发者如何组织他们的代码：

• 从 crate 根节点开始: 当编译一个 crate, 编译器首先在 crate 根文件（通常，对于一个库 crate 而言是src/lib.rs，对于一个二进制 crate 而言是src/main.rs）中寻找需要被编译的代码。

• 声明模块: 在 crate 根文件中可以声明一个新模块，如用mod garden声明了一个叫做garden的模块，编译器会在下列路径中寻找模块代码：

  • 内联，在大括号中，当mod garden后方不是一个分号而是一个大括号
  • 在文件 src/garden.rs
  • 在文件 src/garden/mod.rs

• 声明子模块: 在除了 crate 根节点以外的其他文件中可以定义子模块，如在src/garden.rs中定义了mod vegetables，编译器会在以父模块命名的目录中寻找子模块代码：

  • 内联，在大括号中，当mod vegetables后方不是一个分号而是一个大括号
  • 在文件 src/garden/vegetables.rs
  • 在文件 src/garden/vegetables/mod.rs

• 模块中的代码路径: 在同一个 crate 内，只要隐私规则允许，可以从任意位置引用该模块的代码。如可以通过 crate::garden::vegetables::Asparagus 来引用 garden vegetables 模块下的 Asparagus 类型。

• 私有 vs 公用: 一个模块里的代码默认对其父模块私有，为了使一个模块公用应当在声明时使用 pub mod 替代 mod，为了使一个公用模块内部的成员公用应当在声明前使用 pub。

• use 关键字: 在一个作用域内，可以用 use关键字创建了一个成员的快捷方式来减少长路径的重复，如在crate::garden::vegetables::Asparagus的作用域可以通过 use crate::garden::vegetables::Asparagus;创建一个快捷方式，然后就可以在作用域中只写Asparagus来使用该类型。

创建一个名为backyard的二进制 crate 来说明这些规则，该 crate 的路径同样命名为backyard，文件目录如下：

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

这个例子中的 crate 根文件是src/main.rs，内容如下：

use crate::garden::vegetables::Asparagus;

//告诉编译器应该包含在src/garden.rs文件中发现的代码
pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("I'm growing {:?}!", plant);
}

文件 src/garden.rs 代码如下：

//在src/garden/vegetables.rs中的代码也应该被包括
pub mod vegetables;

文件 src/garden/vegetables.rs 代码如下：

#[derive(Debug)]
pub struct Asparagus {}

在模块中对相关代码进行分组

模块可以将一个 crate 中的代码进行分组，提高可读性和重用性。模块内的代码默认是私有的，可以利用模块的私有性来控制访问权限，私有项是外部无法使用的内部实现细节。同时，我们可以标记模块及其内部的项为公开，使外部代码可以使用和依赖它们。

执行 cargo new --lib restaurant 创建一个新的名为 restaurant 的库，文件 src/lib.rs 代码如下：

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

        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}

        fn serve_order() {}

        fn take_payment() {}
    }
}

上面示例中的模块树的结构如下：

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

注：src/main.rs 和 src/lib.rs 之所以被叫做 crate 根，是因为这两个文件的内容都分别在 crate 模块结构的根组成了一个名为 crate 的模块，该结构被称为 模块树（module tree）。

整个模块树都植根于名为 crate 的隐式模块下，模块树的结构类似于电脑上文件系统的目录树。

引用模块项目的路径

来看一下 Rust 如何在模块树中找到一个项的位置，调用一个函数需要知道它的路径，路径有两种形式：

• 绝对路径（absolute path）是以 crate 根（root）开头的全路径，对于外部 crate 的代码是以 crate 名开头的绝对路径，对于当前 crate 的代码则以字面值 crate 开头。
• 相对路径（relative path）从当前模块开始，以 self、super 或当前模块的标识符开头。

注：绝对路径和相对路径都后跟一个或多个由双冒号（::）分割的标识符。

使用绝对路径和相对路径来调用 add_to_waitlist 函数：

//无法通过编译：hosting 模块是私有的
mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
    }
}

// front_of_house 模块在模块树中与 eat_at_restaurant 定义在同一层级
pub fn eat_at_restaurant() {
    // 绝对路径
    crate::front_of_house::hosting::add_to_waitlist();

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

一般更倾向于使用绝对路径，因为把代码定义和项调用各自独立地移动是更常见的。

在 Rust 中，默认所有项（函数、方法、结构体、枚举、模块和常量）对父模块都是私有的，父模块中的项不能使用子模块中的私有项，但是子模块中的项可以使用它们父模块中的项。

使用 pub 关键字暴露路径

为 mod hosting 和 fn add_to_waitlist 添加 pub 关键字使它们可以在 eat_at_restaurant 函数中被调用：

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

pub fn eat_at_restaurant() {
    // 绝对路径
    crate::front_of_house::hosting::add_to_waitlist();

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

如果你计划共享你的库 crate 以便其它项目可以使用你的代码，公有 API 将是决定 crate 用户如何与你代码交互的契约。关于管理公有 API 的修改以便被人更容易依赖你的库的考量，可以参考 The Rust API Guidelines。

二进制和库 crate 包的最佳实践

我们提到过包可以同时包含一个 src/main.rs 二进制 crate 根和一个 src/lib.rs 库 crate 根，并且这两个 crate 默认以包名来命名。通常，这种包含二进制 crate 和库 crate 的模式的包，在二进制 crate 中只有足够的代码来启动一个可执行文件，可执行文件调用库 crate 的代码。又因为库 crate 可以共享，这使得其它项目从包提供的大部分功能中受益。

模块树应该定义在 src/lib.rs 中，这样通过以包名开头的路径，公有项就可以在二进制 crate 中使用。二进制 crate 就完全变成了同其它 外部 crate 一样的库 crate 的用户：它只能使用公有 API。这有助于你设计一个好的 API；你不仅仅是作者，也是用户！

super 开始的相对路径

可以通过在路径的开头使用 super 从父模块开始构建相对路径，而不是从当前模块或者 crate 根开始，这类似以 .. 语法开始一个文件系统路径。
使用以 super 开头的相对路径从父目录开始调用函数：

fn deliver_order() {}

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

    fn cook_order() {}
}

当认为 back_of_house 模块和 deliver_order 函数之间可能具有某种关联关系，并且重新组织 crate 的模块树时需要一起移动，我们就可以使用 super。

创建公有的结构体和枚举

可以使用 pub 来设计公有的结构体和枚举，如果在一个结构体定义的前面使用了 pub 结构体会变成公有的，但是这个结构体的字段仍然是私有的。带有公有和私有字段的结构体：

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() {
    // 在夏天订购一个黑麦土司作为早餐
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // 改变主意更换想要面包的类型
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // 如果取消下一行的注释代码不能编译；
    // 不允许查看或修改早餐附带的季节水果
    // meal.seasonal_fruit = String::from("blueberries");
}

back_of_house::Breakfast 具有私有字段，必须提供一个公共的关联函数来构造 Breakfast 的实例 ，否则将无法在 eat_at_restaurant 中创建 Breakfast 实例。

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

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;
}

枚举成员不是公有的会显得用处不大，因此枚举成员默认就是公有的。结构体通常使用时不必将它们的字段公有化，因此结构体遵循常规内容默认全部是私有的。

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

不得不编写路径来调用函数显得不便且重复，可以使用 use 关键字创建一个短路径，然后就可以在作用域中的任何地方使用这个更短的名字。通过 use 引入作用域的路径也会检查私有性，同其它路径一样。

通过在 crate 根增加 use crate::front_of_house::hosting，现在 hosting 在作用域中就是有效的名称了，如同 hosting 模块被定义于 crate 根一样：

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

use crate::front_of_house::hosting;

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

use 只能创建 use 所在的特定作用域内的短路径：

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

use crate::front_of_house::hosting;

mod customer {
    pub fn eat_at_restaurant() {
        //编译器错误：短路径不在适用于 customer 模块中
        hosting::add_to_waitlist(); 
    }
}

如果想修复这个编译错误，可以将 use 移动到 customer 模块内，或者在子模块 customer 内通过 super::hosting 引用父模块中的这个短路径。

创建惯用的 use 路径.

使用 use 引入函数

使用 use 将 add_to_waitlist 函数引入作用域并不符合习惯：

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();
}

要想使用 use 将函数的父模块引入作用域，必须在调用函数时指定父模块以表明函数不是在本地定义的，同时使完整路径的重复度最小化。

使用 use 引入结构体、枚举和其他项

将 HashMap 结构体引入作用域的习惯用法：

use std::collections::HashMap;

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

使用 use 引入结构体、枚举和其他项时，习惯是指定它们的完整路径，这是一种惯例。

使用 use 的例外用法

如果想使用 use 语句将两个具有相同名称的项带入作用域则需要指定父模块，将两个具有相同名称但不同父模块的 Result 类型引入作用域：

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

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

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

使用 as 关键字提供新的名称

使用 use 将两个同名类型引入同一作用域这个问题还有另一个解决办法：在这个类型的路径后面使用 as 指定一个新的本地名称或者别名。
通过 as 重命名其中一个 Result 类型：

use std::fmt::Result;
//选择 IoResult 作为 std::io::Result 的新名称
use std::io::Result as IoResult;

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

fn function2() -> IoResult<()> {
    // --snip--
}

使用 pub use 重导出名称

使用 use 关键字将某个名称导入当前作用域后，这个名称在此作用域中就可以使用了，但它对此作用域之外还是私有的。如果想让其他人调用我们的代码时也能够正常使用这个名称，那可以将 pub 和 use 合起来使用，这种技术被称为 “重导出（re-exporting）”。

通过 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();
}

使用外部包

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

rand = "0.8.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..=100);
}

std 标准库也是外部 crate，只是无需修改 Cargo.toml 来引入 std，但需要通过 use 将标准库中定义的项引入项目包的作用域中来引用它们：

use std::collections::HashMap;

嵌套路径来消除大量的 use 行

当需要引入很多定义于相同包或相同模块的项时，为每一项单独列出一行会占用源码很大的空间。有两行 use 语句都从 std 引入项到作用域：

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

可以使用嵌套路径将相同的项在一行中引入作用域，指定嵌套的路径在一行中将多个带有相同前缀的项引入作用域：

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

可以在路径的任何层级使用嵌套路径，这在组合两个共享子路径的 use 语句时非常有用。通过两行 use 语句引入两个路径，其中一个是另一个的子路径：

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

为了在一行 use 语句中引入这两个路径，可以在嵌套路径中使用 self：

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

通过 glob 运算符将所有的公有定义引入作用域

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

//将 std::collections 中定义的所有公有项引入当前作用
use std::collections::*;

使用 glob 运算符时需要小心，Glob 会使得我们难以推导作用域中有什么名称和它们是在何处定义的。
glob 运算符经常用于测试模块 tests 中，这时会将所有内容引入作用域。

将模块拆分成多个文件

当模块变得更大时可能会将它们的定义移动到单独的文件中，从而使代码更容易阅读。

声明 front_of_house 模块，其内容将位于 src/front_of_house.rs：

mod front_of_house;

pub use crate::front_of_house::hosting;

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

在 src/front_of_house.rs 中定义 front_of_house 模块：

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

mod 不同于其他编程语言中看到的 "include" 操作，它更依赖于代码文件目录。

为了移动 hosting，修改 src/front_of_house.rs 使之仅包含 hosting 模块的声明：

pub mod hosting;

接着创建一个 src/front_of_house 目录和一个包含 hosting 模块定义的 hosting.rs 文件：

pub fn add_to_waitlist() {}

编译器所遵循的哪些文件对应哪些模块的代码的规则，意味着目录和文件更接近于模块树。

另一种文件路径

前面介绍了 Rust 编译器所最常用的文件路径，不过另一种更老的文件路径也仍然是支持的。

• 对于声明于 crate 根的 front_of_house 模块，编译器会在如下位置查找模块代码：

  • src/front_of_house.rs（我们所介绍的）
  • src/front_of_house/mod.rs（老风格，不过仍然支持）

• 对于 front_of_house 的子模块 hosting，编译器会在如下位置查找模块代码：

  • src/front_of_house/hosting.rs（我们所介绍的）
  • src/front_of_house/hosting/mod.rs（老风格，不过仍然支持）

如果同一模块同时使用这两种路径风格，会得到一个编译错误。在同一项目中的不同模块混用不同的路径风格是允许的，不过这会使他人感到疑惑。

使用 mod.rs 这一文件名的风格的主要缺点是会导致项目中出现很多 mod.rs 文件，当在编辑器中同时打开它们时对程序员很不友好。

标签：use,Crate,crate,pub,模块,house,Rust,mod
From： https://www.cnblogs.com/timefiles/p/17958617