以前一直是写C的，对于现代语言的错误处理一直是搞不太懂，不过目前看来Rust的错误处理看起来还是比Java顺眼一点的

panic与不可恢复的错误

panic就类似于程序崩溃，程序会直接崩溃掉，这种错误是无法被程序处理的

有的时候代码出问题了，而你对此束手无策。对于这种情况，Rust 有 panic!宏。当执行这个宏时，程序会打印出一个错误信息，展开并清理栈数据，然后接着退出。出现这种情况的场景通常是检测到一些类型的 bug，而且开发者并不清楚该如何处理它。

当出现 panic 时，程序默认会开始 展开（unwinding），这意味着 Rust 会回溯栈并清理它遇到的每一个函数的数据，不过这个回溯并清理的过程有很多工作。另一种选择是直接 终止（abort），这会不清理数据就退出程序。那么程序所使用的内存需要由操作系统来清理。如果你需要项目的最终二进制文件越小越好，panic 时通过在 Cargo.toml 的 [profile] 部分增加 panic = 'abort'，可以由展开切换为终止。例如，如果你想要在release模式中 panic 时直接终止：

1 2	[profile.release] panic = 'abort'

让我们在一个简单的程序中调用 panic!：

1
2
3

fn main() {
    panic!("crash and burn");
}

运行程序将会出现类似这样的输出：

1
2
3
4
5
6

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished dev [unoptimized + debuginfo] target(s) in 0.25s
     Running `target/debug/panic`
thread 'main' panicked at 'crash and burn', src/main.rs:2:5
note: Run with `RUST_BACKTRACE=1` for a backtrace.

最后两行包含 panic! 调用造成的错误信息。第一行显示了 panic 提供的信息并指明了源码中 panic 出现的位置：src/main.rs:2:5 表明这是 src/main.rs 文件的第二行第五个字符。

在这个例子中，被指明的那一行是我们代码的一部分，而且查看这一行的话就会发现 panic! 宏的调用。在其他情况下，panic! 可能会出现在我们的代码所调用的代码中。错误信息报告的文件名和行号可能指向别人代码中的 panic! 宏调用，而不是我们代码中最终导致 panic! 的那一行。我们可以使用 panic! 被调用的函数的 backtrace 来寻找代码中出问题的地方。下面我们会详细介绍 backtrace 是什么。

backtrace宏的作用就是让我们可以找到“我们编写的代码中导致程序崩溃的地方”

1
2
3
4
5

fn main() {
    let v = vec![1, 2, 3];

    v[99];
}

这是一个越界调用，在C语言中，这段代码会运行，然后给你一个错误的值，这是相当危险的

为了使程序远离这类漏洞，如果尝试读取一个索引不存在的元素，Rust 会停止执行并拒绝继续。尝试运行上面的程序会出现如下：

1
2
3
4
5
6

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished dev [unoptimized + debuginfo] target(s) in 0.27s
     Running `target/debug/panic`
thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 99', libcore/slice/mod.rs:2448:10
note: Run with `RUST_BACKTRACE=1` for a backtrace.

这指向了一个不是我们编写的文件，libcore/slice/mod.rs。其为 Rust 源码中 slice 的实现。这是当对 vector v 使用 [] 时 libcore/slice/mod.rs 中会执行的代码，也是真正出现 panic! 的地方。

接下来的几行提醒我们可以设置 RUST_BACKTRACE 环境变量来得到一个 backtrace。backtrace 是一个执行到目前位置所有被调用的函数的列表。Rust 的 backtrace 跟其他语言中的一样：阅读 backtrace 的关键是从头开始读直到发现你编写的文件。这就是问题的发源地。这一行往上是你的代码所调用的代码；往下则是调用你的代码的代码。这些行可能包含核心 Rust 代码，标准库代码或用到的 crate 代码。让我们将 RUST_BACKTRACE 环境变量设置为任何不是 0 的值来获取 backtrace 看看。示例 9-2 展示了与你看到类似的输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

$ RUST_BACKTRACE=1 cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/panic`
thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 99', libcore/slice/mod.rs:2448:10
stack backtrace:
   0: std::sys::unix::backtrace::tracing::imp::unwind_backtrace
             at libstd/sys/unix/backtrace/tracing/gcc_s.rs:49
   1: std::sys_common::backtrace::print
             at libstd/sys_common/backtrace.rs:71
             at libstd/sys_common/backtrace.rs:59
   2: std::panicking::default_hook::{{closure}}
             at libstd/panicking.rs:211
   3: std::panicking::default_hook
             at libstd/panicking.rs:227
   4: <std::panicking::begin_panic::PanicPayload<A> as core::panic::BoxMeUp>::get
             at libstd/panicking.rs:476
   5: std::panicking::continue_panic_fmt
             at libstd/panicking.rs:390
   6: std::panicking::try::do_call
             at libstd/panicking.rs:325
   7: core::ptr::drop_in_place
             at libcore/panicking.rs:77
   8: core::ptr::drop_in_place
             at libcore/panicking.rs:59
   9: <usize as core::slice::SliceIndex<[T]>>::index
             at libcore/slice/mod.rs:2448
  10: core::slice::<impl core::ops::index::Index<I> for [T]>::index
             at libcore/slice/mod.rs:2316
  11: <alloc::vec::Vec<T> as core::ops::index::Index<I>>::index
             at liballoc/vec.rs:1653
  12: panic::main
             at src/main.rs:4
  13: std::rt::lang_start::{{closure}}
             at libstd/rt.rs:74
  14: std::panicking::try::do_call
             at libstd/rt.rs:59
             at libstd/panicking.rs:310
  15: macho_symbol_search
             at libpanic_unwind/lib.rs:102
  16: std::alloc::default_alloc_error_hook
             at libstd/panicking.rs:289
             at libstd/panic.rs:392
             at libstd/rt.rs:58
  17: std::rt::lang_start
             at libstd/rt.rs:74
  18: panic::main

这种信息一般是从下往上读，直到找到我们自己编写的代码位置

RUST_BACKTRACE=1 cargo run

我们可以通过终端传递这个环境变量的值来进入BACKTRACE。

现在让我们回到C语言

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

#include <stdio.h>  // 用于 printf
#include <limits.h> // 用于 INT_MIN

/**
 * @brief 执行两个整数的除法。
 *
 * @param numerator 被除数。
 * @param denominator 除数。
 * @return int 如果除数不为零，返回计算出的商。
 * 如果除数为零，返回 INT_MIN 表示错误。
 */
int safe_divide(int numerator, int denominator) {
    if (denominator == 0) {
        fprintf(stderr, "Error: Division by zero is not allowed.\n");
        return INT_MIN; // 传播错误：返回一个特殊值表示失败
    }
    return numerator / denominator; // 成功：返回计算结果
}

int main() {
    int result;

    printf("--- 正常除法示例 ---\n");
    result = safe_divide(10, 2);
    if (result != INT_MIN) { // 检查返回值是否是错误码
        printf("10 / 2 = %d\n", result); // 成功处理
    } else {
        printf("Error occurred during division.\n"); // 错误处理
    }

    printf("\n--- 除数为零示例 ---\n");
    result = safe_divide(10, 0);
    if (result != INT_MIN) { // 检查返回值是否是错误码
        printf("10 / 0 = %d\n", result); // 理论上不会执行到这里
    } else {
        printf("Error occurred during division. Cannot divide by zero.\n"); // 错误处理
    }

    printf("\n--- 另一个正常除法示例 ---\n");
    result = safe_divide(-15, 3);
    if (result != INT_MIN) {
        printf("-15 / 3 = %d\n", result);
    } else {
        printf("Error occurred during division.\n");
    }

    return 0;
}

当我们写一个除法程序，当我们传”0”为除数，程序很明显不应该崩溃，而是该返回一个标记值来提醒调用者出错了，然后调用者再进行处理，这就是可恢复的错误以及错误的传播。

C语言中错误的传播相对原始，一般都是通过返回值层层传递，一旦有一层忘记处理这种情况，整个程序的稳定性就会受到极大的影响。

在讨论Rust中错误的传播前，我们先来讨论Rust对于这种可恢复错误的处理方式。

在 Rust 中，Option<T> 和 Result<T, E> 是两个非常核心的枚举（enum），它们是 Rust 强大的错误处理和存在性（presence）管理机制的基石。它们的设计理念是强制你在编译时处理可能缺失的值或可能发生的错误，从而避免了其他语言中常见的空指针异常和未处理的运行时错误。

Option<T>：处理值可能缺失的情况

Option<T> 枚举用来表示一个值可能存在，也可能不存在的情况。它的定义如下：

1
2
3
4

enum Option<T> {
    None, // 值不存在
    Some(T), // 值存在，并包含类型 T 的数据
}

它解决什么问题？

在许多其他语言（如 C++、Java、Python 等）中，你可能会使用 NULL、null 或 None 来表示一个变量没有值。然而，直接使用这些“空”值往往会导致运行时错误，比如著名的空指针异常（Null Pointer Exception）。因为你可能会忘记检查一个值是否为 null，然后尝试对其进行操作。

Option<T> 强制你在编译时就处理值存在或不存在的两种情况。如果你尝试直接使用一个 Option<T> 中的值而不先确定它是否是 Some(T)，编译器会报错。

Result<T, E>：处理可能发生的错误

Result<T, E> 枚举用来表示一个操作可能成功并返回一个值，也可能失败并返回一个错误。它的定义如下：

1
2
3
4

enum Result<T, E> {
    Ok(T),  // 操作成功，并包含类型 T 的结果数据
    Err(E), // 操作失败，并包含类型 E 的错误数据
}

它解决什么问题？

在 C 语言中，你通常通过返回值和错误码来表示函数成功或失败。在 Java/Python 等语言中，则通常使用异常（exceptions）。然而，这些方式都有其弊端：

• C 语言的错误码：容易被忽略，需要手动检查，且错误信息有限。
• 异常：虽然方便，但可能会导致控制流难以预测（“goto 式的错误处理”），且编译器通常不会强制你捕获或声明异常，可能导致未处理的运行时崩溃。

Result<T, E> 强制你在编译时就考虑并处理成功和失败的两种情况，使得错误处理成为你代码类型系统的一部分。

如何使用？

与 Option 类似，你通常会使用 match 表达式、if let 或 Result 提供的各种方法（如 is_ok(), is_err(), unwrap(), expect(), map_err(), and_then(), ? 运算符等）来处理 Result 值。

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

use std::fs::File; // 引入文件系统模块

fn main() {
    // 尝试打开一个不存在的文件
    // File::open 返回一个 Result<File, std::io::Error>
    let greeting_file = File::open("hello.txt");
    let greeting_file = match greeting_file {
      Ok(file) => file,
      Err(error) => {
         panic!("Probled opening the file {:?}",error) 
        }, 
    };

    // 如果上面一行没有 panic，说明文件成功打开了
    println!("文件 'hello.txt' 已成功打开！");

    // 注意：如果 hello.txt 不存在，上面的 println! 永远不会执行
}

这是Rust中最简单的错误处理，通过match匹配Result<>成员来实现对于错误的处理，但是在上面那段程序中，当打开文件失败时，程序直接崩溃掉了，这很明显不是我们想要的结果，接下来我们引入下一个知识点 错误的匹配

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let f = File::open("hello.txt");

    let f = match f {
        Ok(file) => file,
        Err(error) => match error.kind() {
            ErrorKind::NotFound => match File::create("hello.txt") {
                Ok(fc) => fc,
                Err(e) => panic!("Problem creating the file: {:?}", e),
            },
            other_error => panic!("Problem opening the file: {:?}", other_error),
        },
    };
}

File::open 返回的 Err 成员中的值类型 io::Error，它是一个标准库中提供的结构体。这个结构体有一个返回 io::ErrorKind 值的 kind 方法可供调用。io::ErrorKind 是一个标准库提供的枚举，它的成员对应 io 操作可能导致的不同错误类型。我们感兴趣的成员是 ErrorKind::NotFound，它代表尝试打开的文件并不存在。这样，match 就匹配完 f 了，不过对于 error.kind() 还有一个内层 match。

我们希望在内层 match 中检查的条件是 error.kind() 的返回值是否为 ErrorKind的 NotFound 成员。如果是，则尝试通过 File::create 创建文件。然而因为 File::create 也可能会失败，还需要增加一个内层 match 语句。当文件不能被打开，会打印出一个不同的错误信息。外层 match 的最后一个分支保持不变，这样对任何除了文件不存在的错误会使程序 panic。

match确实是强大的，但是有时候我们确实是希望当出现错误时直接panic!掉，此时再写match会有点麻烦，Rust为我们提供了两个简写方法。

unwrap和expect

1
2
3
4
5

use std::fs::File;

fn main() {
    let f = File::open("hello.txt").unwrap();
}

如果调用这段代码时不存在 hello.txt 文件，我们将会看到一个 unwrap 调用 panic! 时提供的错误信息：

1
2
3

thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Error {
repr: Os { code: 2, message: "No such file or directory" } }',
src/libcore/result.rs:906:4

还有另一个类似于 unwrap 的方法它还允许我们选择 panic! 的错误信息：expect。使用 expect 而不是 unwrap 并提供一个好的错误信息可以表明你的意图并更易于追踪 panic 的根源。expect 的语法看起来像这样：

1
2
3
4
5

use std::fs::File;

fn main() {
    let f = File::open("hello.txt").expect("Failed to open hello.txt");
}

expect 与 unwrap 的使用方式一样：返回文件句柄或调用 panic! 宏。expect 在调用 panic! 时使用的错误信息将是我们传递给 expect 的参数，而不像 unwrap 那样使用默认的 panic! 信息。它看起来像这样：

1
2

thread 'main' panicked at 'Failed to open hello.txt: Error { repr: Os { code:
2, message: "No such file or directory" } }', src/libcore/result.rs:906:4

因为这个错误信息以我们指定的文本开始，Failed to open hello.txt，将会更容易找到代码中的错误信息来自何处。如果在多处使用 unwrap，则需要花更多的时间来分析到底是哪一个 unwrap 造成了 panic，因为所有的 unwrap 调用都打印相同的信息。

接下来我们就可以进入到下一个知识点 错误的传播，C语言一般都是通过返回值的层层传递来实现错误的传播。传播错误的好处就是这样能更好地控制代码调用，因为比起你代码所拥有的上下文，调用者可能拥有更多信息或逻辑来决定应该如何处理错误。

简单点说错误的传播就是把可能发生的错误返回给调用者，让调用者来处理而不是由被调用的函数来处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

#![allow(unused)]
fn main() {
use std::io;
use std::io::Read;
use std::fs::File;

fn read_username_from_file() -> Result<String, io::Error> {
    let f = File::open("hello.txt");

    let mut f = match f {
        Ok(file) => file,
        Err(e) => return Err(e),
    };

    let mut s = String::new();

    match f.read_to_string(&mut s) {
        Ok(_) => Ok(s),
        Err(e) => Err(e),
    }
}
}

首先让我们看看函数的返回值：Result<String, io::Error>。这意味着函数返回一个 Result<T, E> 类型的值，其中泛型参数 T 的具体类型是 String，而 E 的具体类型是 io::Error。如果这个函数没有出任何错误成功返回，函数的调用者会收到一个包含 String 的 Ok 值 —— 函数从文件中读取到的用户名。如果函数遇到任何错误，函数的调用者会收到一个 Err 值，它储存了一个包含更多这个问题相关信息的 io::Error 实例。这里选择 io::Error 作为函数的返回值是因为它正好是函数体中那两个可能会失败的操作的错误返回值：File::open 函数和 read_to_string 方法。

函数体以 File::open 函数开头。接着使用 match 处理返回值 Result，类似于示例 9-4 中的 match，唯一的区别是当 Err 时不再调用 panic!，而是提早返回并将 File::open 返回的错误值作为函数的错误返回值传递给调用者。如果 File::open 成功了，我们将文件句柄储存在变量 f 中并继续。

接着我们在变量 s 中创建了一个新 String 并调用文件句柄 f 的 read_to_string 方法来将文件的内容读取到 s 中。read_to_string 方法也返回一个 Result 因为它也可能会失败：哪怕是 File::open 已经成功了。所以我们需要另一个 match 来处理这个 Result：如果 read_to_string 成功了，那么这个函数就成功了，并返回文件中的用户名，它现在位于被封装进 Ok 的 s 中。如果 read_to_string 失败了，则像之前处理 File::open 的返回值的 match 那样返回错误值。不过并不需要显式的调用 return，因为这是函数的最后一个表达式。

调用这个函数的代码最终会得到一个包含用户名的 Ok 值，或者一个包含 io::Error 的 Err 值。我们无从得知调用者会如何处理这些值。例如，如果他们得到了一个 Err 值，他们可能会选择 panic! 并使程序崩溃、使用一个默认的用户名或者从文件之外的地方寻找用户名。我们没有足够的信息知晓调用者具体会如何尝试，所以将所有的成功或失败信息向上传播，让他们选择合适的处理方法。

这种写法是相当常见的，Rust也为我们提供了这种情况下可供使用的简写

传播错误的简写：? 运算符

示例 9-7 展示了一个 read_username_from_file 的实现，它实现了与示例 9-6 中的代码相同的功能，不过这个实现使用了 ? 运算符：

1
2
3
4
5
6
7
8
9
10

use std::io;
use std::io::Read;
use std::fs::File;

fn read_username_from_file() -> Result<String, io::Error> {
    let mut f = File::open("hello.txt")?;
    let mut s = String::new();
    f.read_to_string(&mut s)?;
    Ok(s)
}

示例 9-7：一个使用 ? 运算符向调用者返回错误的函数

Result 值之后的 ? 被定义为与示例 9-6 中定义的处理 Result 值的 match 表达式有着完全相同的工作方式。如果 Result 的值是 Ok，这个表达式将会返回 Ok 中的值而程序将继续执行。如果值是 Err，Err 将作为整个函数的返回值，就好像使用了 return 关键字一样，这样错误值就被传播给了调用者。

示例 9-6 中的 match 表达式与问号运算符所做的有一点不同：? 运算符所使用的错误值被传递给了 from 函数，它定义于标准库的 From trait 中，其用来将错误从一种类型转换为另一种类型。当 ? 运算符调用 from 函数时，收到的错误类型被转换为由当前函数返回类型所指定的错误类型。这在当函数返回单个错误类型来代表所有可能失败的方式时很有用，即使其可能会因很多种原因失败。只要每一个错误类型都实现了 from 函数来定义如何将自身转换为返回的错误类型，? 运算符会自动处理这些转换。

在示例 9-7 的上下文中，File::open 调用结尾的 ? 将会把 Ok 中的值返回给变量 f。如果出现了错误，? 运算符会提早返回整个函数并将一些 Err 值传播给调用者。同理也适用于 read_to_string 调用结尾的 ?。

当你在一个不返回 Result 的函数中需要调用返回 Result 的函数时，文本提供了两种主要的修复方法：

1. 修改当前函数的返回值类型为 Result<T, E>： 这是最常见和推荐的方法，特别是当你的函数确实需要传播错误时。你将函数的签名从默认的 () 修改为 Result<T, E>，使得它能够兼容 ? 运算符传播的错误。

   示例：

   Rust

   1 2 3 4 5 6 7 8 9 10 11

   use std::error::Error; // 引入 Error trait use std::fs::File; // 将 main 函数的返回值类型修改为 Result<(), Box<dyn Error>> fn main() -> Result<(), Box<dyn Error>> { let f = File::open("hello.txt")?; // 现在 ? 运算符可以正常工作了 // ... 其他操作 ... Ok(()) // 如果所有操作成功，返回 Ok(()) }

   • -> Result<(), Box<dyn Error>>：这里 main 函数被声明为返回一个 Result。
     • Ok(()) 表示成功，没有具体返回值。
     • Err(Box<dyn Error>) 表示失败，并包含一个错误对象。
   • Box<dyn Error>：这被称为 “trait 对象”。它的作用是允许你返回任何实现了 std::error::Error 这个 trait 的错误类型。这是 Rust 处理“多种可能错误类型”的一种通用方法。在这里，你可以简单地理解为 main 函数现在可以返回任何类型的错误，只要这个错误实现了 Error trait。

2. 在当前函数内使用 match 或 Result 的其他方法处理错误： 如果你不希望函数传播错误，或者函数不能修改返回值类型（例如，一些回调函数），那么你就必须在当前函数内部显式地处理 Result，而不是使用 ? 运算符。

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   use std::fs::File; fn main() { // main 函数的返回值仍然是 () // 使用 match 显式处理 File::open 返回的 Result let f = match File::open("hello.txt") { Ok(file) => file, Err(e) => { eprintln!("Error opening file: {}", e); // 打印错误到标准错误输出 return; // 如果发生错误，直接从 main 函数返回，程序终止 } }; println!("File opened successfully!"); // ... 继续使用 f ... }

   在这个例子中，我们使用 match 语句来检查 File::open 的结果。如果它返回 Err，我们就打印错误信息并使用 return; 提前退出 main 函数。这样就没有错误需要被“传播”出 main 函数了。

RUST标准库中给我们提供了很多集合,这里介绍三种最常见的:

1. vector
2. String
3. hash map

可能是类似于CPP中的STL,标准库提供了一些别的数据类型,方便我们使用.

Vector

第一个类型是 Vec<T>，也被称为 vector。vector 允许我们在一个单独的数据结构中储存多个值，所有值在内存中彼此相邻排列。vector 只能储存相同类型的值。它们在拥有一系列项的场景下非常实用，例如文件中的文本行或购物车中商品的价格。

Vector的初始化

1. ler v:Vec[i32] = Vec::new(); 新建一个空的Vec来存储i32类型的值.
2. let v = vec![1,2,3]; 利用vec!宏来使用初始值来创建一个Vec.此时Rust可以自动推断出v的类型.

Vector的更新

1
2
3
4
5
6
7
8
9

#![allow(unused)]
fn main() {
let mut v = Vec::new();
v.push(5);
v.push(6);
v.push(7);
v.push(8);
}

很明显,v.push是将值推入Vec中的方法

我们需要注意的一点是:与其他结构类似,当vector离开他的作用域时会被销毁,并且当存在一个有效的不可变引用时,是没办法通过push向vec中新增值的.

1
2
3
4

let mut v = vec![1, 2, 3, 4, 5];
let first = &v[0];
v.push(6);
println!("The first element is: {}", first);

Vector元素的读取

1. 通过索引来读取值
2. 通过.get来读取值

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#![allow(unused)]
fn main() {
let v = vec![1, 2, 3, 4, 5];

let third: &i32 = &v[2];
println!("The third element is {}", third);

match v.get(2) {
    Some(third) => println!("The third element is {}", third),
    None => println!("There is no third element."),
}
}

这里有两个需要注意的地方。首先，我们使用索引值 2 来获取第三个元素，索引是从 0 开始的。其次，这两个不同的获取第三个元素的方式分别为：使用 & 和 [] 返回一个引用；或者使用 get 方法以索引作为参数来返回一个 Option<&T>。

使用.get方法可能是更优的,因为当索引越界时,.get方法会返回None,然后你就可以处理而不至于使程序崩溃

遍历Vector中的元素

如果想要依次访问 vector 中的每一个元素，我们可以遍历其所有的元素而无需通过索引一次一个的访问。

1
2
3
4

let v = vec![100, 32, 57];
for i in &v {
    println!("{}", i);
}

我们也可以遍历可变 vector 的每一个元素的可变引用以便能改变他们。

1
2
3
4

let mut v = vec![100, 32, 57];
for i in &mut v {
    *i += 50;
}

为了修改可变引用所指向的值，在使用 += 运算符之前必须使用解引用运算符（*）获取 i 中的值。

使用枚举来储存多种类型

在本章的开始，我们提到 vector 只能储存相同类型的值。这是很不方便的；绝对会有需要储存一系列不同类型的值的用例。幸运的是，枚举的成员都被定义为相同的枚举类型，所以当需要在 vector 中储存不同类型值时，我们可以定义并使用一个枚举！

例如，假如我们想要从电子表格的一行中获取值，而这一行的有些列包含数字，有些包含浮点值，还有些是字符串。我们可以定义一个枚举，其成员会存放这些不同类型的值，同时所有这些枚举成员都会被当作相同类型，那个枚举的类型。接着可以创建一个储存枚举值的 vector，这样最终就能够储存不同类型的值了。

1
2
3
4
5
6
7
8
9
10
11
12

enum SpreadsheetCell {
    Int(i32),
    Float(f64),
    Text(String),
}

let row = vec![
    SpreadsheetCell::Int(3),
    SpreadsheetCell::Text(String::from("blue")),
    SpreadsheetCell::Float(10.12),
];

Rust 在编译时就必须准确的知道 vector 中类型的原因在于它需要知道储存每个元素到底需要多少内存。第二个好处是可以准确的知道这个 vector 中允许什么类型。如果 Rust 允许 vector 存放任意类型，那么当对 vector 元素执行操作时一个或多个类型的值就有可能会造成错误。使用枚举外加 match 意味着 Rust 能在编译时就保证总是会处理所有可能的情况，正如第 6 章讲到的那样。

如果在编写程序时不能确切无遗地知道运行时会储存进 vector 的所有类型，枚举技术就行不通了。相反，你可以使用 trait 对象，第 17 章会讲到它。

现在我们了解了一些使用 vector 的最常见的方式，请一定去看看标准库中 Vec 定义的很多其他实用方法的 API 文档。例如，除了 push 之外还有一个 pop 方法，它会移除并返回 vector 的最后一个元素。

String类型

在 Rust 中，字符串并非单一类型，而是通常指两种主要的 UTF-8 编码类型：str（字符串 slice） 和 String。

具体来说，它涵盖了以下几个要点：

• str (字符串 slice)：
  • 这是 Rust 核心语言中唯一的字符串类型。
  • 它通常以 被借用的形式 &str 出现。
  • &str 是对储存在别处（例如程序二进制输出中的字符串字面量）的 UTF-8 编码字符串数据的引用。它们是不可变且固定大小的。
• String：
  • 这是由 Rust 标准库提供的类型，不属于核心语言。
  • 它是一种可增长的、可变的、有所有权的 UTF-8 编码字符串类型。
  • String 类型的数据存储在堆上，可以根据需要进行扩展和修改。
• “字符串”的通用指代：
  • 当 Rust 开发者（Rustacean）提到“字符串”时，通常指的是 String 和 &str 这两种类型，而不是特指其中一个。
  • 这两种类型在 Rust 标准库中都非常常用，且都使用 UTF-8 编码。
• 其他字符串类型：
  • 除了 String 和 &str，Rust 标准库还提供了其他字符串类型，如 OsString、OsStr、CString 和 CStr。
  • 这些类型通常以 String 或 Str 结尾，分别对应其所有权（String 变体）和可借用（Str 变体）的特性。
  • 它们可能用于存储不同编码或内存表示形式的文本内容（例如与操作系统或 C 语言交互时）。

官方文档下头这段写得还是很像人话的,我们之间复制过来,需要注意的是,rust中的字符串默认是UTF-8而不是ASCII,所以会出现一些在C语言中不会出现的问题,C语言中与之对应的知识是wchar,即宽字符.

新建字符串

很多 Vec 可用的操作在 String 中同样可用，从 new 函数创建字符串开始，如示例 8-11 所示。

1

let mut s = String::new();

示例 8-11：新建一个空的 String

这新建了一个叫做 s 的空的字符串，接着我们可以向其中装载数据。通常字符串会有初始数据，因为我们希望一开始就有这个字符串。为此，可以使用 to_string 方法，它能用于任何实现了 Display trait 的类型，字符串字面量也实现了它。示例 8-12 展示了两个例子。

1
2
3
4
5
6

let data = "initial contents";

let s = data.to_string();

// 该方法也可直接用于字符串字面量：
let s = "initial contents".to_string();

示例 8-12：使用 to_string 方法从字符串字面量创建 String

这些代码会创建包含 initial contents 的字符串。

也可以使用 String::from 函数来从字符串字面量创建 String。示例 8-13 中的代码等同于使用 to_string。

1

let s = String::from("initial contents");

示例 8-13：使用 String::from 函数从字符串字面量创建 String

因为字符串应用广泛，这里有很多不同的用于字符串的通用 API 可供选择。其中一些可能看起来多余，不过都有其用武之地！在这个例子中，String::from 和 to_string 最终做到了完全相同的事情，所以如何选择，就是风格问题了。

请记住，字符串是 UTF-8 编码的，所以可以包含任何正确编码的数据，如示例 8-14 所示。

1
2
3
4
5
6
7
8
9
10
11

let hello = String::from("السلام عليكم");
let hello = String::from("Dobrý den");
let hello = String::from("Hello");
let hello = String::from("שָׁלוֹם");
let hello = String::from("नमस्ते");
let hello = String::from("こんにちは");
let hello = String::from("안녕하세요");
let hello = String::from("你好");
let hello = String::from("Olá");
let hello = String::from("Здравствуйте");
let hello = String::from("Hola");

示例 8-14：在字符串中储存不同语言的问候语

所有这些都是有效的 String 值。

更新字符串

String 的大小可以增加，其内容也可以改变，就像可以放入更多数据来改变 Vec 的内容一样。另外，可以方便的使用 + 运算符或 format! 宏来拼接 String 值。

使用 push_str 和 push 附加字符串

可以通过 push_str 方法来附加字符串 slice，从而使 String 变长，如示例 8-15 所示。

1
2

let mut s = String::from("foo");
s.push_str("bar");

示例 8-15：使用 push_str 方法向 String 附加字符串 slice

执行这两行代码之后，s 将会包含 foobar。push_str 方法采用字符串 slice，因为我们并不需要获取参数的所有权。例如，示例 8-16 展示了如果将 s2 的内容附加到 s1 之后，自身不能被使用就糟糕了。

1
2
3
4

let mut s1 = String::from("foo");
let s2 = "bar";
s1.push_str(s2);
println!("s2 is {}", s2);

示例 8-16：将字符串 slice 的内容附加到 String 后使用它

如果 push_str 方法获取了 s2 的所有权，就不能在最后一行打印出其值了。好在代码如我们期望那样工作！

push 方法被定义为获取一个单独的字符作为参数，并附加到 String 中。示例 8-17 展示了使用 push 方法将字母 l 加入 String 的代码。

1
2

let mut s = String::from("lo");
s.push('l');

示例 8-17：使用 push 将一个字符加入 String 值中

执行这些代码之后，s 将会包含 lol。

使用 + 运算符或 format! 宏拼接字符串

通常你会希望将两个已知的字符串合并在一起。一种办法是像这样使用 + 运算符，如示例 8-18 所示。

1
2
3

let s1 = String::from("Hello, ");
let s2 = String::from("world!");
let s3 = s1 + &s2; // 注意 s1 被移动了，不能继续使用

示例 8-18：使用 + 运算符将两个 String 值合并到一个新的 String 值中

执行完这些代码之后，字符串 s3 将会包含 Hello, world!。s1 在相加后不再有效的原因，和使用 s2 的引用的原因，与使用 + 运算符时调用的函数签名有关。+ 运算符使用了 add 函数，这个函数签名看起来像这样：

1

fn add(self, s: &str) -> String {

这并不是标准库中实际的签名；标准库中的 add 使用泛型定义。这里我们看到的 add 的签名使用具体类型代替了泛型，这也正是当使用 String 值调用这个方法会发生的。第 10 章会讨论泛型。这个签名提供了理解 + 运算那微妙部分的线索。

首先，s2 使用了 &，意味着我们使用第二个字符串的 引用 与第一个字符串相加。这是因为 add 函数的 s 参数：只能将 &str 和 String 相加，不能将两个 String 值相加。不过等一下 —— 正如 add 的第二个参数所指定的，&s2 的类型是 &String 而不是 &str。那么为什么示例 8-18 还能编译呢？

之所以能够在 add 调用中使用 &s2 是因为 &String 可以被 强转（coerced）成 &str。当 add 函数被调用时，Rust 使用了一个被称为 解引用强制转换（deref coercion）的技术，你可以将其理解为它把 &s2 变成了 &s2[..]。第 15 章会更深入的讨论解引用强制转换。因为 add 没有获取参数的所有权，所以 s2 在这个操作后仍然是有效的 String。

其次，可以发现签名中 add 获取了 self 的所有权，因为 self 没有 使用 &。这意味着示例 8-18 中的 s1 的所有权将被移动到 add 调用中，之后就不再有效。虽然 let s3 = s1 + &s2; 看起来就像它会复制两个字符串并创建一个新的字符串，而实际上这个语句会获取 s1 的所有权，附加上从 s2 中拷贝的内容，并返回结果的所有权。换句话说，它看起来好像生成了很多拷贝，不过实际上并没有：这个实现比拷贝要更高效。

如果想要级联多个字符串，+ 的行为就显得笨重了：

1
2
3
4
5

let s1 = String::from("tic");
let s2 = String::from("tac");
let s3 = String::from("toe");

let s = s1 + "-" + &s2 + "-" + &s3;

这时 s 的内容会是 tic-tac-toe。在有这么多 + 和 " 字符的情况下，很难理解具体发生了什么。对于更为复杂的字符串连接，可以使用 format! 宏：

1
2
3
4
5

let s1 = String::from("tic");
let s2 = String::from("tac");
let s3 = String::from("toe");

let s = format!("{}-{}-{}", s1, s2, s3);

这些代码也会将 s 设置为 “tic-tac-toe”。format! 与 println! 的工作原理相同，不过不同于将输出打印到屏幕上，它返回一个带有结果内容的 String。这个版本就好理解的多，并且不会获取任何参数的所有权。

索引字符串

在很多语言中，通过索引来引用字符串中的单独字符是有效且常见的操作。然而在 Rust 中，如果你尝试使用索引语法访问 String 的一部分，会出现一个错误。考虑一下如示例 8-19 中所示的无效代码。

1
2

let s1 = String::from("hello");
let h = s1[0];

示例 8-19：尝试对字符串使用索引语法

这段代码会导致如下错误：

1
2
3
4
5
6
7

error[E0277]: the trait bound `std::string::String: std::ops::Index<{integer}>` is not satisfied
 -->
  |
3 |     let h = s1[0];
  |             ^^^^^ the type `std::string::String` cannot be indexed by `{integer}`
  |
  = help: the trait `std::ops::Index<{integer}>` is not implemented for `std::string::String`

错误和提示说明了全部问题：Rust 的字符串不支持索引。那么接下来的问题是，为什么不支持呢？为了回答这个问题，我们必须先聊一聊 Rust 是如何在内存中储存字符串的。

内部表现

String 是一个 Vec<u8> 的封装。让我们看看示例 8-14 中一些正确编码的字符串的例子。首先是这一个：

1

let len = String::from("Hola").len();

在这里，len 的值是 4 ，这意味着储存字符串 “Hola” 的 Vec 的长度是 4 个字节：这里每一个字母的 UTF-8 编码都占用 1 个字节。那下面这个例子又如何呢？（注意这个字符串中的首字母是西里尔字母的 Ze，而不是阿拉伯数字 3 。）

1

let len = String::from("Здравствуйте").len();

当问及这个字符是多长的时候有人可能会说是 12。然而，Rust 的回答是 24。这是使用 UTF-8 编码 “Здравствуйте” 所需要的字节数，这是因为每个 Unicode 标量值需要 2 个字节存储。因此一个字符串字节值的索引并不总是对应一个有效的 Unicode 标量值。作为演示，考虑如下无效的 Rust 代码：

1
2

let hello = "Здравствуйте";
let answer = &hello[0];

answer 的值应该是什么呢？它应该是第一个字符 З 吗？当使用 UTF-8 编码时，З 的第一个字节 208，第二个是 151，所以 answer 实际上应该是 208，不过 208 自身并不是一个有效的字母。返回 208 可不是一个请求字符串第一个字母的人所希望看到的，不过它是 Rust 在字节索引 0 位置所能提供的唯一数据。用户通常不会想要一个字节值被返回，即便这个字符串只有拉丁字母： 即便 &"hello"[0] 是返回字节值的有效代码，它也应当返回 104 而不是 h。为了避免返回意外的值并造成不能立刻发现的 bug，Rust 根本不会编译这些代码，并在开发过程中及早杜绝了误会的发生。

字节、标量值和字形簇！天呐！

这引起了关于 UTF-8 的另外一个问题：从 Rust 的角度来讲，事实上有三种相关方式可以理解字符串：字节、标量值和字形簇（最接近人们眼中 字母 的概念）。

比如这个用梵文书写的印度语单词 “नमस्ते”，最终它储存在 vector 中的 u8 值看起来像这样：

1

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164, 224, 165, 135]

这里有 18 个字节，也就是计算机最终会储存的数据。如果从 Unicode 标量值的角度理解它们，也就像 Rust 的 char 类型那样，这些字节看起来像这样：

1

['न', 'म', 'स', '्', 'त', 'े']

这里有六个 char，不过第四个和第六个都不是字母，它们是发音符号本身并没有任何意义。最后，如果以字形簇的角度理解，就会得到人们所说的构成这个单词的四个字母：

1

["न", "म", "स्", "ते"]

Rust 提供了多种不同的方式来解释计算机储存的原始字符串数据，这样程序就可以选择它需要的表现方式，而无所谓是何种人类语言。

最后一个 Rust 不允许使用索引获取 String 字符的原因是，索引操作预期总是需要常数时间 (O(1))。但是对于 String 不可能保证这样的性能，因为 Rust 必须从开头到索引位置遍历来确定有多少有效的字符。

字符串 slice

索引字符串通常是一个坏点子，因为字符串索引应该返回的类型是不明确的：字节值、字符、字形簇或者字符串 slice。因此，如果你真的希望使用索引创建字符串 slice 时，Rust 会要求你更明确一些。为了更明确索引并表明你需要一个字符串 slice，相比使用 [] 和单个值的索引，可以使用 [] 和一个 range 来创建含特定字节的字符串 slice：

1
2

let hello = "Здравствуйте";
let s = &hello[0..4];

这里，s 会是一个 &str，它包含字符串的头 4 个字节。早些时候，我们提到了这些字母都是 2 个字节长的，所以这意味着 s 将会是 “Зд”。

如果获取 &hello[0..1] 会发生什么呢？答案是：Rust 在运行时会 panic，就跟访问 vector 中的无效索引时一样：

1

thread 'main' panicked at 'byte index 1 is not a char boundary; it is inside 'З' (bytes 0..2) of `Здравствуйте`', src/libcore/str/mod.rs:2188:4

你应该小心谨慎的使用这个操作，因为这么做可能会使你的程序崩溃。

遍历字符串的方法

幸运的是，这里还有其他获取字符串元素的方式。

如果你需要操作单独的 Unicode 标量值，最好的选择是使用 chars 方法。对 “नमस्ते” 调用 chars 方法会将其分开并返回六个 char 类型的值，接着就可以遍历其结果来访问每一个元素了：

1
2
3

for c in "नमस्ते".chars() {
    println!("{}", c);
}

这些代码会打印出如下内容：

1
2
3
4
5
6

न
म
स
्
त
े

bytes 方法返回每一个原始字节，这可能会适合你的使用场景：

1
2
3

for b in "नमस्ते".bytes() {
    println!("{}", b);
}

这些代码会打印出组成 String 的 18 个字节：

1
2
3
4
5

224
164
// --snip--
165
135

不过请记住有效的 Unicode 标量值可能会由不止一个字节组成。

从字符串中获取字形簇是很复杂的，所以标准库并没有提供这个功能。crates.io 上有些提供这样功能的 crate。

字符串并不简单

总而言之，字符串还是很复杂的。不同的语言选择了不同的向开发者展示其复杂性的方式。Rust 选择了以准确的方式处理 String 数据作为所有 Rust 程序的默认行为，这意味着开发者们必须更多的思考如何预先处理 UTF-8 数据。这种权衡取舍相比其他语言更多的暴露出了字符串的复杂性，不过也使你在开发生命周期后期免于处理涉及非 ASCII 字符的错误。

哈希map,我在C语言编程时没怎么接触过这个东西,所以不太熟悉,等用到的时候再回来看吧

哈希 map 储存键值对

最后介绍的常用集合类型是 哈希 map（hash map）。HashMap<K, V> 类型储存了一个键类型 K 对应一个值类型 V 的映射。它通过一个 哈希函数（hashing function）来实现映射，决定如何将键和值放入内存中。很多编程语言支持这种数据结构，不过通常有不同的名字：哈希、map、对象、哈希表或者关联数组，仅举几例。

哈希 map 可以用于需要任何类型作为键来寻找数据的情况，而不是像 vector 那样通过索引。例如，在一个游戏中，你可以将每个团队的分数记录到哈希 map 中，其中键是队伍的名字而值是每个队伍的分数。给出一个队名，就能得到他们的得分。

本章我们会介绍哈希 map 的基本 API，不过还有更多吸引人的功能隐藏于标准库在 HashMap<K, V> 上定义的函数中。一如既往请查看标准库文档来了解更多信息。

新建一个哈希 map

可以使用 new 创建一个空的 HashMap，并使用 insert 增加元素。在示例 8-20 中我们记录两支队伍的分数，分别是蓝队和黄队。蓝队开始有 10 分而黄队开始有 50 分：

1
2
3
4
5
6

use std::collections::HashMap;

let mut scores = HashMap::new();

scores.insert(String::from("Blue"), 10);
scores.insert(String::from("Yellow"), 50);

示例 8-20：新建一个哈希 map 并插入一些键值对

注意必须首先 use 标准库中集合部分的 HashMap。在这三个常用集合中，HashMap 是最不常用的，所以并没有被 prelude 自动引用。标准库中对 HashMap 的支持也相对较少，例如，并没有内建的构建宏。

像 vector 一样，哈希 map 将它们的数据储存在堆上，这个 HashMap 的键类型是 String 而值类型是 i32。类似于 vector，哈希 map 是同质的：所有的键必须是相同类型，值也必须都是相同类型。

另一个构建哈希 map 的方法是使用一个元组的 vector 的 collect 方法，其中每个元组包含一个键值对。collect 方法可以将数据收集进一系列的集合类型，包括 HashMap。例如，如果队伍的名字和初始分数分别在两个 vector 中，可以使用 zip 方法来创建一个元组的 vector，其中 “Blue” 与 10 是一对，依此类推。接着就可以使用 collect 方法将这个元组 vector 转换成一个 HashMap，如示例 8-21 所示：

1
2
3
4
5
6

use std::collections::HashMap;

let teams  = vec![String::from("Blue"), String::from("Yellow")];
let initial_scores = vec![10, 50];

let scores: HashMap<_, _> = teams.iter().zip(initial_scores.iter()).collect();

示例 8-21：用队伍列表和分数列表创建哈希 map

这里 HashMap<_, _> 类型标注是必要的，因为 collect 有可能当成多种不同的数据结构，而除非显式指定否则 Rust 无从得知你需要的类型。但是对于键和值的类型参数来说，可以使用下划线占位，而 Rust 能够根据 vector 中数据的类型推断出 HashMap 所包含的类型。

哈希 map 和所有权

对于像 i32 这样的实现了 Copy trait 的类型，其值可以拷贝进哈希 map。对于像 String 这样拥有所有权的值，其值将被移动而哈希 map 会成为这些值的所有者，如示例 8-22 所示：

1
2
3
4
5
6
7
8
9

use std::collections::HashMap;

let field_name = String::from("Favorite color");
let field_value = String::from("Blue");

let mut map = HashMap::new();
map.insert(field_name, field_value);
// 这里 field_name 和 field_value 不再有效，
// 尝试使用它们看看会出现什么编译错误！

示例 8-22：展示一旦键值对被插入后就为哈希 map 所拥有

当 insert 调用将 field_name 和 field_value 移动到哈希 map 中后，将不能使用这两个绑定。

如果将值的引用插入哈希 map，这些值本身将不会被移动进哈希 map。但是这些引用指向的值必须至少在哈希 map 有效时也是有效的。第 10 章 “生命周期与引用有效性” 部分将会更多的讨论这个问题。

访问哈希 map 中的值

可以通过 get 方法并提供对应的键来从哈希 map 中获取值，如示例 8-23 所示：

1
2
3
4
5
6
7
8
9

use std::collections::HashMap;

let mut scores = HashMap::new();

scores.insert(String::from("Blue"), 10);
scores.insert(String::from("Yellow"), 50);

let team_name = String::from("Blue");
let score = scores.get(&team_name);

示例 8-23：访问哈希 map 中储存的蓝队分数

这里，score 是与蓝队分数相关的值，应为 Some(10)。因为 get 返回 Option<V>，所以结果被装进 Some；如果某个键在哈希 map 中没有对应的值，get 会返回 None。这时就要用某种第 6 章提到的方法之一来处理 Option。

可以使用与 vector 类似的方式来遍历哈希 map 中的每一个键值对，也就是 for 循环：

1
2
3
4
5
6
7
8
9
10

use std::collections::HashMap;

let mut scores = HashMap::new();

scores.insert(String::from("Blue"), 10);
scores.insert(String::from("Yellow"), 50);

for (key, value) in &scores {
    println!("{}: {}", key, value);
}

这会以任意顺序打印出每一个键值对：

1
2

Yellow: 50
Blue: 10

更新哈希 map

尽管键值对的数量是可以增长的，不过任何时候，每个键只能关联一个值。当我们想要改变哈希 map 中的数据时，必须决定如何处理一个键已经有值了的情况。可以选择完全无视旧值并用新值代替旧值。可以选择保留旧值而忽略新值，并只在键 没有 对应值时增加新值。或者可以结合新旧两值。让我们看看这分别该如何处理！

覆盖一个值

如果我们插入了一个键值对，接着用相同的键插入一个不同的值，与这个键相关联的旧值将被替换。即便示例 8-24 中的代码调用了两次 insert，哈希 map 也只会包含一个键值对，因为两次都是对蓝队的键插入的值：

1
2
3
4
5
6
7
8
9

use std::collections::HashMap;

let mut scores = HashMap::new();

scores.insert(String::from("Blue"), 10);
scores.insert(String::from("Blue"), 25);

println!("{:?}", scores);

示例 8-24：替换以特定键储存的值

这会打印出 {"Blue": 25}。原始的值 10 则被覆盖了。

只在键没有对应值时插入

我们经常会检查某个特定的键是否有值，如果没有就插入一个值。为此哈希 map 有一个特有的 API，叫做 entry，它获取我们想要检查的键作为参数。entry 函数的返回值是一个枚举，Entry，它代表了可能存在也可能不存在的值。比如说我们想要检查黄队的键是否关联了一个值。如果没有，就插入值 50，对于蓝队也是如此。使用 entry API 的代码看起来像示例 8-25 这样：

1
2
3
4
5
6
7
8
9
10

use std::collections::HashMap;

let mut scores = HashMap::new();
scores.insert(String::from("Blue"), 10);

scores.entry(String::from("Yellow")).or_insert(50);
scores.entry(String::from("Blue")).or_insert(50);

println!("{:?}", scores);

示例 8-25：使用 entry 方法只在键没有对应一个值时插入

Entry 的 or_insert 方法在键对应的值存在时就返回这个值的可变引用，如果不存在则将参数作为新值插入并返回新值的可变引用。这比编写自己的逻辑要简明的多，另外也与借用检查器结合得更好。

运行示例 8-25 的代码会打印出 {"Yellow": 50, "Blue": 10}。第一个 entry 调用会插入黄队的键和值 50，因为黄队并没有一个值。第二个 entry 调用不会改变哈希 map 因为蓝队已经有了值 10。

根据旧值更新一个值

另一个常见的哈希 map 的应用场景是找到一个键对应的值并根据旧的值更新它。例如，示例 8-26 中的代码计数一些文本中每一个单词分别出现了多少次。我们使用哈希 map 以单词作为键并递增其值来记录我们遇到过几次这个单词。如果是第一次看到某个单词，就插入值 0。

1
2
3
4
5
6
7
8
9
10
11
12
13

use std::collections::HashMap;

let text = "hello world wonderful world";

let mut map = HashMap::new();

for word in text.split_whitespace() {
    let count = map.entry(word).or_insert(0);
    *count += 1;
}

println!("{:?}", map);

示例 8-26：通过哈希 map 储存单词和计数来统计出现次数

这会打印出 {"world": 2, "hello": 1, "wonderful": 1}，or_insert 方法事实上会返回这个键的值的一个可变引用（&mut V）。这里我们将这个可变引用储存在 count 变量中，所以为了赋值必须首先使用星号（*）解引用 count。这个可变引用在 for 循环的结尾离开作用域，这样所有这些改变都是安全的并符合借用规则。

哈希函数

HashMap 默认使用一种 “密码学安全的”（“cryptographically strong” ）1 哈希函数，它可以抵抗拒绝服务（Denial of Service, DoS）攻击。然而这并不是可用的最快的算法，不过为了更高的安全性值得付出一些性能的代价。如果性能监测显示此哈希函数非常慢，以致于你无法接受，你可以指定一个不同的 hasher 来切换为其它函数。hasher 是一个实现了 BuildHasher trait 的类型。第 10 章会讨论 trait 和如何实现它们。你并不需要从头开始实现你自己的 hasher；crates.io 有其他人分享的实现了许多常用哈希算法的 hasher 的库。

我们依旧先来欣赏一下官方的高速神言,这一节官方主要就是讲了一下 use as还有pub use这三个东西

使用 use 关键字将名称引入作用域

到目前为止，似乎我们编写的用于调用函数的路径都很冗长且重复，并不方便。例如，示例 7-7 中，无论我们选择 add_to_waitlist 函数的绝对路径还是相对路径，每次我们想要调用 add_to_waitlist 时，都必须指定 front_of_house 和 hosting。幸运的是，有一种方法可以简化这个过程。我们可以使用 use 关键字将路径一次性引入作用域，然后调用该路径中的项，就如同它们是本地项一样。

在示例 7-11 中，我们将 crate::front_of_house::hosting 模块引入了 eat_at_restaurant 函数的作用域，而我们只需要指定 hosting::add_to_waitlist 即可在 eat_at_restaurant 中调用 add_to_waitlist 函数。

1
2
3
4
5
6
7
8
9
10
11
12

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

示例 7-11: 使用 use 将模块引入作用域

在作用域中增加 use 和路径类似于在文件系统中创建软连接（符号连接，symbolic link）。通过在 crate 根增加 use crate::front_of_house::hosting，现在 hosting 在作用域中就是有效的名称了，如同 hosting 模块被定义于 crate 根一样。通过 use 引入作用域的路径也会检查私有性，同其它路径一样。

你还可以使用 use 和相对路径来将一个项引入作用域。示例 7-12 展示了如何指定相对路径来取得与示例 7-11 中一样的行为。

1
2
3
4
5
6
7
8
9
10
11
12

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

use front_of_house::hosting;

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

示例 7-12: 使用 use 和相对路径将模块引入作用域

创建惯用的 use 路径

在示例 7-11 中，你可能会比较疑惑，为什么我们是指定 use crate::front_of_house::hosting，然后在 eat_at_restaurant 中调用 hosting::add_to_waitlist，而不是通过指定一直到 add_to_waitlist 函数的 use 路径来得到相同的结果，如示例 7-13 所示。

1
2
3
4
5
6
7
8
9
10
11
12

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

示例 7-13: 使用 use 将 add_to_waitlist 函数引入作用域，这并不符合习惯

虽然示例 7-11 和 7-13 都完成了相同的任务，但示例 7-11 是使用 use 将函数引入作用域的习惯用法。使用 use 将函数的父模块引入作用域意味着我们必须在调用函数时指定父模块，这样可以清晰地表明函数不是在本地定义的，同时使完整路径的重复度最小化。示例 7-13 中的代码则未表明 add_to_waitlist 是在哪里被定义的。

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

1
2
3
4
5
6
7

use std::collections::HashMap;

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

示例 7-14: 将 HashMap 引入作用域的习惯用法

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

其实也就说了这么些内容

使用 use 引入函数时，习惯上是将函数的父模块引入作用域。 这样，在调用函数时，你需要写 父模块::函数名()，比如 hosting::add_to_waitlist()。这样做的好处是，可以清晰地表明这个函数不是当前模块定义的，同时避免了每次都写完整的冗长路径。

使用 use 引入结构体、枚举或其他项时，习惯上是直接引入到该项本身。 这样，你可以直接使用该项的名称，比如 HashMap::new()。

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

1
2
3
4
5
6
7
8
9
10
11

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

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

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

示例 7-15: 使用父模块将两个具有相同名称的类型引入同一作用域

如你所见，使用父模块可以区分这两个 Result 类型。如果我们是指定 use std::fmt::Result 和 use std::io::Result，我们将在同一作用域拥有了两个 Result 类型，当我们使用 Result 时，Rust 则不知道我们要用的是哪个。

接下来就是引入 as

1
2
3
4
5
6
7
8
9
10

use std::fmt::Result;
use std::io::Result as IoResult;

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

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

　这个其实看两眼也就明白了,不用什么复杂的解释

然后还有pub use,我的理解就是你自己编写的模块中通过use引用了别的模块的内容,想要使这些内容可以被引用你模块的人使用的话,就需要pub use语句

以下是ai给出的解释

pub use 的核心作用，正是你描述的这个场景：当你编写一个模块（或者库）时，你可能会在内部 use 其他模块或类型来方便自己使用。但是，如果你希望使用你这个模块的外部代码也能通过你的模块路径来访问这些被你 use 进来的内容，那么你就需要使用 pub use。

简单来说：

• use： 仅仅是你自己模块内部的“快捷方式”，方便你在本模块中使用。外部模块无法通过你的模块来访问这些被 use 进来的东西。
• pub use： 不仅创建了内部的“快捷方式”，还公开了这个快捷方式。这样，外部模块就可以通过你的模块路径来访问这个被重导出的内容，就好像这些内容就是你模块自己定义的一样。

这就像是你开了一家商店（你的模块），你从批发商那里进了些商品（其他模块的内容）。

• 如果你只是自己用（use），这些商品就在你的库房里，只有你能看到。
• 但如果你想把这些商品摆在你的店里卖（pub use），那么顾客（外部代码）就可以通过你的商店来购买这些商品了，他们甚至不需要知道你最初是从哪个批发商那里进的货。

pub use 允许你提供一个更清晰、更简洁的 API 给你的用户，同时隐藏了你内部的组织结构,语法如下:

1
2
3
4
5
6
7
8
9
10
11
12
13

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

还剩下一些杂七杂八的东西

下面是这段内容讲的三个主要“玩意儿”：

• 你问得很好！这段内容主要围绕着如何在 Rust 项目中使用外部包（crate）以及如何优化 use 语句来管理这些引入的依赖。

  下面是这段内容讲的三个主要“玩意儿”：

  1. 如何使用外部包（Crate）

  Rust 项目使用 Cargo 这个构建系统和包管理器来管理依赖。

  • 声明依赖： 当你需要使用一个外部包时（比如 rand），你需要在项目的 Cargo.toml 文件中的 [dependencies] 部分添加这个包的名称和版本号。Cargo 会自动从 crates.io（Rust 社区的包注册表）下载这个包及其所有必要的依赖。

    Ini, TOML

    1 2	[dependencies] rand = "0.8.3" # 示例：声明对rand包的依赖

  • 引入作用域： 仅仅声明依赖还不够。你还需要使用 use 关键字，以 绝对路径 的方式将外部包中你想要使用的特定项（函数、结构体、trait 等）引入到你的代码的作用域中，这样你才能直接使用它们。

    Rust

    1	use rand::Rng; // 将rand包中的Rng trait引入作用域

    值得注意的是，标准库 (std) 也是一个特殊的外部 crate。虽然你不需要在 Cargo.toml 中声明它，但你仍然需要使用 use 语句来引入 std 中你想要使用的项，例如 use std::collections::HashMap;。

  2. 优化 use 语句：嵌套路径

  当你的代码需要从同一个模块或同一个包中引入多个项时，逐行 use 会让代码变得冗长。Rust 提供了 嵌套路径 的语法来简化这个过程。

  • 基本嵌套： 如果多个项共享同一个路径前缀，你可以将它们用大括号 {} 包裹起来。

    Rust

    1 2 3 4 5 6

    // 之前： // use std::cmp::Ordering; // use std::io; // 之后：一行搞定 use std::{cmp::Ordering, io};

  • self 关键字： 当你想引入一个模块本身，同时又想引入这个模块下的某个子项时，可以在嵌套路径中使用 self 关键字。

    Rust

    1 2 3 4 5 6

    // 之前： // use std::io; // use std::io::Write; // 之后：一行搞定，同时引入了io模块和io::Write use std::io::{self, Write};

  3. 引入所有公有定义：Glob 运算符 *

  如果你想将一个模块下所有 公有 的项都引入到当前作用域，可以使用 glob 运算符 \*。

  • 用法： 在路径的末尾加上 *。

    Rust

    1	use std::collections::*; // 引入std::collections模块中所有的公有项

  • 注意事项： 尽管方便，但使用 glob 运算符时需要谨慎。它会使代码的可读性降低，因为你很难一眼看出某个名称是来自哪里，可能会导致名称冲突。它通常在测试模块（为了方便测试所有功能）或特定模式（如 prelude 模式）中使用。

  这里还有，并提供了两种技巧 ({} 嵌套路径和 * glob 运算符) 来更简洁地管理 use 语句，从而提高代码的可读性和维护性。

  这段代码展示了 Rust 中更细粒度的可见性控制，也就是如何使用 pub(in path)、pub(self) 和 pub(super) 来限制一个项（比如函数）的可见范围。

  深入理解 Rust 的可见性控制

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105

  // 一个名为 `my_mod` 的模块 mod my_mod { // 模块中的项默认具有私有的可见性 fn private_function() { println!("called `my_mod::private_function()`"); } // 使用 `pub` 修饰语来改变默认可见性。 pub fn function() { println!("called `my_mod::function()`"); } // 在同一模块中，项可以访问其它项，即使它是私有的。 pub fn indirect_access() { print!("called `my_mod::indirect_access()`, that\n> "); private_function(); } // 模块也可以嵌套 pub mod nested { pub fn function() { println!("called `my_mod::nested::function()`"); } #[allow(dead_code)] fn private_function() { println!("called `my_mod::nested::private_function()`"); } // 使用 `pub(in path)` 语法定义的函数只在给定的路径中可见。 // `path` 必须是父模块（parent module）或祖先模块（ancestor module） pub(in crate::my_mod) fn public_function_in_my_mod() { print!("called `my_mod::nested::public_function_in_my_mod()`, that\n > "); public_function_in_nested() } // 使用 `pub(self)` 语法定义的函数则只在当前模块中可见。 pub(self) fn public_function_in_nested() { println!("called `my_mod::nested::public_function_in_nested"); } // 使用 `pub(super)` 语法定义的函数只在父模块中可见。 pub(super) fn public_function_in_super_mod() { println!("called my_mod::nested::public_function_in_super_mod"); } } pub fn call_public_function_in_my_mod() { print!("called `my_mod::call_public_funcion_in_my_mod()`, that\n> "); nested::public_function_in_my_mod(); print!("> "); nested::public_function_in_super_mod(); } // `pub(crate)` 使得函数只在当前 crate 中可见 pub(crate) fn public_function_in_crate() { println!("called `my_mod::public_function_in_crate()"); } // 嵌套模块的可见性遵循相同的规则 mod private_nested { #[allow(dead_code)] pub fn function() { println!("called `my_mod::private_nested::function()`"); } } } fn function() { println!("called `function()`"); } fn main() { // 模块机制消除了相同名字的项之间的歧义。 function(); my_mod::function(); // 公有项，包括嵌套模块内的，都可以在父模块外部访问。 my_mod::indirect_access(); my_mod::nested::function(); my_mod::call_public_function_in_my_mod(); // pub(crate) 项可以在同一个 crate 中的任何地方访问 my_mod::public_function_in_crate(); // pub(in path) 项只能在指定的模块中访问 // 报错！函数 `public_function_in_my_mod` 是私有的 //my_mod::nested::public_function_in_my_mod(); // 试一试 ^ 取消该行的注释 // 模块的私有项不能直接访问，即便它是嵌套在公有模块内部的 // 报错！`private_function` 是私有的 //my_mod::private_function(); // 试一试 ^ 取消此行注释 // 报错！`private_function` 是私有的 //my_mod::nested::private_function(); // 试一试 ^ 取消此行的注释 // Error! `private_nested` is a private module //my_mod::private_nested::function(); // 试一试 ^ 取消此行的注释 }

  默认情况下，Rust 中的所有项（函数、结构体、枚举、模块等）都是私有的。要让它们在当前作用域之外可见，你需要使用 pub 关键字。然而，简单的 pub 意味着对所有外部代码都可见，这在某些情况下可能过于宽松。

  pub(in path)、pub(self) 和 pub(super) 提供了一种方式，让你能够更精确地控制项的可见性，而不是简单地“完全公开”或“完全私有”。

  1. pub(in crate::my_mod)：指定路径可见性

  这个语法允许你将一个项的可见性限制在指定的路径（模块）内部。

  • pub(in crate::my_mod) fn public_function_in_my_mod()

    • 这意味着 public_function_in_my_mod 这个函数只在 crate::my_mod 模块及其子模块内部可见和可调用。
    • 在 my_mod 外部的代码，即使 my_mod 本身是公开的，也无法直接调用 public_mod::nested::public_function_in_my_mod。
    • path 必须是该项的父模块或祖先模块。你不能指定一个与当前项没有继承关系的模块。

    想象一下： 你有一个家族企业，my_mod 是总公司。这个函数就像是只有总公司内部的员工（包括子公司员工）才能使用的特定工具。外部客户即使知道总公司存在，也无法直接使用这个工具。

  2. pub(self)：当前模块可见性

  pub(self) 将可见性限制在定义该项的当前模块内部。

  • pub(self) fn public_function_in_nested()

    • 这意味着 public_function_in_nested 这个函数只在 my_mod::nested 模块内部可见。
    • 即使在 my_mod 模块内部（nested 的父模块），也无法直接调用 public_function_in_nested。只有在 nested 模块内部的代码才能调用它。

    想象一下： nested 是公司里的一个特定部门。public_function_in_nested 就像是这个部门内部的专用流程，只有这个部门的员工才能使用。总公司或其他部门的员工都不能直接调用这个流程。

  3. pub(super)：父模块可见性

  pub(super) 将可见性限制在定义该项的父模块内部。

  • pub(super) fn public_function_in_super_mod()

    • 这意味着 public_function_in_super_mod 这个函数只在 my_mod 模块内部可见。
    • 尽管它定义在 nested 模块中，但它只对 nested 的父模块（即 my_mod）可见。nested 模块内部也能调用它，因为父模块的可见性范围包含了子模块。

    想象一下： 仍然是公司里的一个部门 nested。public_function_in_super_mod 就像是这个部门为总公司（my_mod）提供的内部服务，总公司可以直接调用，但其他部门或外部客户不能直接调用。

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50

  fn function() { println!("called `function()`"); } mod cool { pub fn function() { println!("called `cool::function()`"); } } mod my { fn function() { println!("called `my::function()`"); } mod cool { pub fn function() { println!("called `my::cool::function()`"); } } pub fn indirect_call() { // 让我们从这个作用域中访问所有名为 `function` 的函数！ print!("called `my::indirect_call()`, that\n> "); // `self` 关键字表示当前的模块作用域——在这个例子是 `my`。 // 调用 `self::function()` 和直接调用 `function()` 都得到相同的结果， // 因为他们表示相同的函数。 self::function(); function(); // 我们也可以使用 `self` 来访问 `my` 内部的另一个模块： self::cool::function(); // `super` 关键字表示父作用域（在 `my` 模块外面）。 super::function(); // 这将在 *crate* 作用域内绑定 `cool::function` 。 // 在这个例子中，crate 作用域是最外面的作用域。 { use crate::cool::function as root_function; root_function(); } } } fn main() { my::indirect_call(); }

  总结

  这些细粒度的可见性控制非常有用，它们允许你：

  • 封装内部实现细节： 将一些只应该在特定范围内部使用的函数或数据隐藏起来，避免外部滥用或不当修改。
  • 构建清晰的 API： 明确哪些部分是库的公共接口，哪些是内部辅助功能。
  • 增强代码安全性： 限制了对某些敏感操作的访问。

  RUST的这个模块管理系统真的挺复杂的,估计得在实战中用它两回才能真正学得会.

路径用于引用模块树中的项

来看一下 Rust 如何在模块树中找到一个项的位置，我们使用路径的方式，就像在文件系统使用路径一样。如果我们想要调用一个函数，我们需要知道它的路径。

路径有两种形式：

• 绝对路径（absolute path）从 crate 根部开始，以 crate 名或者字面量 crate 开头。
• 相对路径（relative path）从当前模块开始，以 self、super 或当前模块的标识符开头。

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

让我们回到示例 7-1。我们如何调用 add_to_waitlist 函数？还是同样的问题，add_to_waitlist 函数的路径是什么？在示例 7-3 中，我们通过删除一些模块和函数，稍微简化了一下我们的代码。我们在 crate 根部定义了一个新函数 eat_at_restaurant，并在其中展示调用 add_to_waitlist 函数的两种方法。eat_at_restaurant 函数是我们 crate 库的一个公共 API，所以我们使用 pub 关键字来标记它。在“使用 pub 关键字暴露路径”一节，我们将详细介绍 pub。注意，这个例子无法编译通过，我们稍后会解释原因。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

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

    // 相对路径
    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 关键字为起始的绝对路径。

在 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，但是相对路径必须要更新。我们更倾向于使用绝对路径，因为把代码定义和项调用各自独立地移动是更常见的。

官方依旧高速神言不说人话

我们用 C 语言的例子来类比一下 Rust 中“把代码定义和项调用各自独立地移动是更常见的”这句话。

在 C 语言中，我们没有像 Rust 这样的模块系统，但我们可以用头文件（.h） 和 源文件（.c） 来类比“定义”和“调用”以及“路径”。

C 语言中的类比

想象你有两个 C 文件：

1. math_operations.h 和 math_operations.c：

   • math_operations.h (头文件)：声明了 add 函数。这就像 Rust 中一个模块的公开接口，告诉别人有这么一个函数。

     1 2	// math_operations.h int add(int a, int b); // 这是函数的“定义”或“声明”

   • math_operations.c (源文件)：实现了 add 函数。这是函数的具体“定义”所在。

     1 2 3 4 5 6

     // math_operations.c #include "math_operations.h" int add(int a, int b) { return a + b; }

2. main.c：

   • 这个文件会调用 add 函数。

场景一：类似 Rust 中的绝对路径（使用完整路径/包含完整头文件）

在 main.c 中，如果你想要使用 add 函数，你会这么做：

1
2
3
4
5
6
7

// main.c
#include "math_operations.h" // 告诉编译器去哪里找 add 函数的声明

int main() {
    int result = add(5, 3); // 调用 add 函数
    return 0;
}

这里，#include "math_operations.h" 就像 Rust 中的绝对路径。它明确地指明了 add 函数的声明在哪里可以找到。

• 如果我移动 main.c 文件（调用者）：假设你把 main.c 从项目的一个子目录移动到另一个子目录，只要 math_operations.h 的相对位置没有改变，或者你通过编译器的 -I 选项（include path）告诉了编译器 math_operations.h 的新位置，那么 main.c 中 add(5, 3) 的调用不需要修改。因为 add 函数的定义（和声明）本身没有移动。这和 Rust 中绝对路径的稳定性类似。

场景二：类似 Rust 中的相对路径（如果 C 语言有这种直接模块引用）

C 语言没有像 Rust 这样内建的相对模块路径引用机制。但我们可以想象一种情况，如果你需要在 main.c 中直接引用 add 函数的定义，而不是通过头文件。这在 C 语言中是做不到的，但为了类比，我们可以假设：

如果 main.c 直接依赖于 math_operations.c 文件的相对位置来找到 add 函数的定义（这是个假设，C 实际编译不是这样做的）。那么：

• 如果我移动 main.c 文件（调用者）：main.c 的位置变了，它与 math_operations.c 的相对位置就可能变了。那么，原先的“相对路径”就失效了，你需要修改 main.c 中引用 add 函数的方式。

“各自独立移动”的含义

回到 Rust 的语境：

“把代码定义和项调用各自独立地移动是更常见的”这句话意味着：

1. 你更常会移动和重构使用某个功能（add 函数）的代码文件（main.c），而不是改变那个功能本身（math_operations.c 和 math_operations.h）的存放位置。
2. 当你移动 main.c 时，你希望它里面的 add(5, 3) 调用能够保持不变，而不需要每次移动都去修改它。

因此，使用 绝对路径（类似 C 语言中 #include <library_header.h> 或者通过 -I 选项找到的头文件）会更稳定。因为它从一个固定的起点（Rust 的 crate 根部）开始寻找，不依赖于你当前调用代码（main.c）的位置。即使你把 main.c 移动到项目的其他地方，只要 add 函数的定义没有从它原来的“绝对位置”移动，那么对它的引用就依然有效。

而 相对路径，由于它的起点是“当前模块”，一旦你移动了当前模块，相对位置就变了，路径就可能失效，需要你手动更新。

所以，Rust 建议我们倾向于使用绝对路径，因为它在代码重构时，特别是当调用方代码移动时，能够减少你需要修改的引用路径的数量，从而提高代码的维护性和稳定性。

简而言之就是绝对路径更好用,OK,接下来我们继续欣赏官方文档的高速神言

让我们试着编译一下示例 7-3，并查明为何不能编译！示例 7-4 展示了这个错误。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

$ 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();
  |                            ^^^^^^^ 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();
   |                     ^^^^^^^ 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` due to 2 previous errors

示例 7-4: 构建示例 7-3 出现的编译器错误

错误信息说 hosting 模块是私有的。换句话说，我们拥有 hosting 模块和 add_to_waitlist 函数的的正确路径，但是 Rust 不让我们使用，因为它不能访问私有片段。

模块不仅对于你组织代码很有用。他们还定义了 Rust 的 私有性边界（privacy boundary）：这条界线不允许外部代码了解、调用和依赖被封装的实现细节。所以，如果你希望创建一个私有函数或结构体，你可以将其放入模块。

Rust 中默认所有项（函数、方法、结构体、枚举、模块和常量）都是私有的。父模块中的项不能使用子模块中的私有项，但是子模块中的项可以使用他们父模块中的项。这是因为子模块封装并隐藏了他们的实现详情，但是子模块可以看到他们定义的上下文。继续拿餐馆作比喻，把私有性规则想象成餐馆的后台办公室：餐馆内的事务对餐厅顾客来说是不可知的，但办公室经理可以洞悉其经营的餐厅并在其中做任何事情。

Rust 选择以这种方式来实现模块系统功能，因此默认隐藏内部实现细节。这样一来，你就知道可以更改内部代码的哪些部分而不会破坏外部代码。你还可以通过使用 pub 关键字来创建公共项，使子模块的内部部分暴露给上级模块。

接下来主要就是引出PUB关键字,需要注意PUB关键字对于结构体,枚举,函数的作用是不太一样的,需要分辨一下

使用 pub 关键字暴露路径

让我们回头看一下示例 7-4 的错误，它告诉我们 hosting 模块是私有的。我们想让父模块中的 eat_at_restaurant 函数可以访问子模块中的 add_to_waitlist 函数，因此我们使用 pub 关键字来标记 hosting 模块，如示例 7-5 所示。

1
2
3
4
5
6
7
8
9
10
11
12
13

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

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

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

示例 7-5: 使用 pub 关键字声明 hosting 模块使其可在 eat_at_restaurant 使用

不幸的是，示例 7-5 的代码编译仍然有错误，如示例 7-6 所示。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

$ 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` due to 2 previous errors

示例 7-6: 构建示例 7-5 出现的编译器错误

发生了什么？在 mod hosting 前添加了 pub 关键字，使其变成公有的。伴随着这种变化，如果我们可以访问 front_of_house，那我们也可以访问 hosting。但是 hosting 的 内容（contents） 仍然是私有的；这表明使模块公有并不使其内容也是公有的。模块上的 pub 关键字只允许其父模块引用它。

示例 7-6 中的错误说，add_to_waitlist 函数是私有的。私有性规则不但应用于模块，还应用于结构体、枚举、函数和方法。

让我们继续将 pub 关键字放置在 add_to_waitlist 函数的定义之前，使其变成公有。如示例 7-7 所示。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

示例 7-7: 为 mod hosting 和 fn add_to_waitlist 添加 pub 关键字使他们可以在 eat_at_restaurant 函数中被调用

现在代码可以编译通过了！让我们看看绝对路径和相对路径，并根据私有性规则，再检查一下为什么增加 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 是兄弟），我们可以从 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，路径其余的部分也是有效的，因此函数调用也是有效的！

我们来仔细讨论一下上面这段话

front_of_house 在你提供的代码中不是私有的，它是默认公开的，因为它是直接在 crate 根部定义的。

Rust 的访问规则有点绕，我们来具体解释一下：

crate 根部定义的模块默认是公开的

当你直接在 src/lib.rs (或者 src/main.rs) 文件中定义一个模块时，比如 mod front_of_house {}，这个模块就是定义在 crate 的根部。

在 crate 根部定义的项（包括模块），默认情况下是可以在整个 crate 内部被直接访问到的。 它们不需要 pub 关键字就可以被同一 crate 中的其他代码访问。pub 关键字的作用是让该项可以被外部 crate (比如你的库被其他项目引用时) 访问，或者让该项可以被子模块之外的模块通过完整路径访问。

所以，front_of_house 模块虽然没有显式地写 pub mod front_of_house {}，但因为它直接位于 crate 根部，所以：

1. eat_at_restaurant 函数（也在 crate 根部）可以直接看到并访问 front_of_house，因为它们是“兄弟”关系，都在最外层。
2. crate:: 作为绝对路径的起点，它自然也能直接“看到”它根部定义的所有内容，包括 front_of_house。

为什么会产生误解？

你可能误解了“私有”的含义。在 Rust 中，一个模块（或任何项）如果没有 pub 关键字，它通常表示该项只在其直接父模块内部可见和可访问。但是，这个规则对于 crate 根部有点特殊。crate 根部本身就是最高层级，它里面定义的所有东西对于整个 crate 内部的代码来说，都是默认可访问的，除非它们被嵌套在某个私有模块内部。

总结

• front_of_house 模块：因为它直接定义在 crate 根部（src/lib.rs 的顶层），所以默认情况下，这个 crate 内部的所有代码都可以直接看到并引用它。它不是“私有的”，而是对 crate 内部可见的。
• pub mod hosting：这里 pub 的作用是让 hosting 模块可以被 front_of_house 之外的代码（比如 eat_at_restaurant，它位于 front_of_house 的父级 crate 根部）访问。如果没有 pub，那么 hosting 默认就是私有的，只有 front_of_house 内部的代码才能访问它。
• pub fn add_to_waitlist()：函数默认是私有的。如果你想从它所在的模块外面调用它，就必须给它加上 pub。

所以，crate 可以访问到 front_of_house 是因为 front_of_house 就在 crate 根部，并且对于 crate 内部是默认可见的。

依旧AI大法

是的，默认情况下，模块外部无法直接访问 front_of_house 模块的内容。

让我们用刚才的餐厅例子再来说明一下：

你的 Rust 项目是个大餐厅，front_of_house 是餐厅里“前厅”这个区域。

• 默认情况下（没有 pub）：这个“前厅”是餐厅内部的一个区域，它里面的具体设施（比如某个柜台、某个角落）默认都是“不对外开放”的。只有当你身处“前厅”内部，或者你被“前厅”的主管（父模块）特许，才能使用里面的东西。外部的顾客（其他 crate）或者甚至餐厅内部其他区域的员工（其他模块）都不能直接走进“前厅”去拿里面的东西，除非前厅的某个门是打开的（pub）。
• 为什么 crate::front_of_house 可以访问到？
  • 因为 front_of_house 是直接定义在你的 crate（也就是整个餐厅）的“大厅”（根部）里的。
  • 所以，当你从“大厅”出发（crate::）时，你自然能看到“大厅”里所有的区域划分，包括 front_of_house。这就像你站在餐厅大堂中央，能看到哪里是“前厅”，哪里是“厨房”。
  • 但是，能看到这个区域，不代表你就能直接使用这个区域里的所有东西。要使用里面的东西，里面的东西本身也必须是公开的。

所以，结论是：

如果你想让 front_of_house 模块内部的 某个函数或结构体被**front_of_house 模块外部**的代码访问（比如被 eat_at_restaurant 访问，或者被另一个 crate 访问），那么：

1. front_of_house 模块本身需要是可访问的（因为它直接在 crate 根部，所以它对 crate 内部是默认可见的）。
2. front_of_house 内部的子模块或函数/结构体也必须使用 pub 关键字 来声明，才能让外部通过完整路径访问到它们。

这就是为什么在示例中，你不仅要给 hosting 加上 pub，还要给 add_to_waitlist 加上 pub，才能让 eat_at_restaurant 最终调用到它。

使用 super 起始的相对路径

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

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

1
2
3
4
5
6
7
8
9
10
11

fn serve_order() {}

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

    fn cook_order() {}
}

示例 7-8: 使用以 super 开头的相对路径从父目录开始调用函数

fix_incorrect_order 函数在 back_of_house 模块中，所以我们可以使用 super 进入 back_of_house 父模块，也就是本例中的 crate 根。在这里，我们可以找到 serve_order。成功！我们认为 back_of_house 模块和 serve_order 函数之间可能具有某种关联关系，并且，如果我们要重新组织这个 crate 的模块树，需要一起移动它们。因此，我们使用 super，这样一来，如果这些代码被移动到了其他模块，我们只需要更新很少的代码。

创建公有的结构体和枚举

我们还可以使用 pub 来设计公有的结构体和枚举，不过有一些额外的细节需要注意。如果我们在一个结构体定义的前面使用了 pub ，这个结构体会变成公有的，但是这个结构体的字段仍然是私有的。我们可以根据情况决定每个字段是否公有。在示例 7-9 中，我们定义了一个公有结构体 back_of_house::Breakfast，其中有一个公有字段 toast 和私有字段 seasonal_fruit。这个例子模拟的情况是，在一家餐馆中，顾客可以选择随餐附赠的面包类型，但是厨师会根据季节和库存情况来决定随餐搭配的水果。餐馆可用的水果变化是很快的，所以顾客不能选择水果，甚至无法看到他们将会得到什么水果。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

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

示例 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 展示的那样。

1
2
3
4
5
6
7
8
9
10
11
12

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。

在C语言编程时，我们会包含多个头文件，然后就可以使用头文件中定义的函数和数据类型。但是C语言这一套容易出现一些问题:

1. 隐式依赖
2. 全局命名空间污染
3. 重复包含问题

RUST的模块系统很好的避免了这些问题

依旧是熟悉的复制粘贴

到目前为止，我们编写的程序都在一个文件的一个模块中。伴随着项目的增长，你应该通过将代码分解为多个模块和多个文件来组织代码。一个包（package）可以包含多个二进制 crate 项和一个可选的库 crate。伴随着包的增长，你可以将包中的部分代码提取出来，做成独立的 crate，这些 crate 则作为外部依赖项。本章将会涵盖所有这些概念。对于一个由一系列相互关联的包组成的超大型项目，Cargo 提供了工作空间（workspaces）这一功能，我们将在第十四章的 “Cargo Workspaces” 对此进行讲解。

我们也会讨论封装来实现细节，这可以让你在更高层面重用代码：你实现了一个操作后，其他的代码可以通过该代码的公共接口来进行调用，而不需要知道它是如何实现的。你在编写代码时可以定义哪些部分是其他代码可以使用的公共部分，以及哪些部分是你有权更改实现细节的私有部分。这是另一种减少你在脑海中记住项目内容数量的方法。

这里有一个需要说明的概念 “作用域（scope）”：代码所在的嵌套上下文有一组定义为 “in scope” 的名称。当阅读、编写和编译代码时，程序员和编译器需要知道特定位置的特定名称是否引用了变量、函数、结构体、枚举、模块、常量或者其他有意义的项。你可以创建作用域，以及改变哪些名称在作用域内还是作用域外。同一个作用域内不能拥有两个相同名称的项；可以使用一些工具来解决名称冲突。

Rust 有许多功能可以让你管理代码的组织，包括哪些细节可以被公开，哪些细节作为私有部分，以及程序中各个作用域中有哪些名称。这些特性，有时被统称为 “模块系统（the module system）”，包括：

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

包和Create

crate 是 Rust 在编译时最小的代码单位。即使你用 rustc 而不是 cargo 来编译一个单独的源代码文件（正如我们在第 1 章“编写并运行 Rust 程序”中所做的那样），编译器还是会将那个文件视为一个 crate。crate 可以包含模块，模块可以定义在其他文件，然后和 crate 一起编译，我们会在接下来的章节中遇到。

crate 有两种形式：二进制 crate 和库 crate。二进制 crate（Binary crates）可以被编译为可执行程序，比如命令行程序或者服务端。它们必须有一个名为 main 函数来定义当程序被执行的时候所需要做的事情。目前我们所创建的 crate 都是二进制 crate。

库 crate（Library crates）并没有 main 函数，它们也不会编译为可执行程序。相反它们定义了可供多个项目复用的功能模块。比如 第二章 的 rand crate 就提供了生成随机数的功能。大多数时间 Rustaceans 说的 “crate” 指的都是库 crate，这与其他编程语言中 “library” 概念一致。

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

**包（package）是提供一系列功能的一个或者多个 crate 的捆绑。**一个包会包含一个 Cargo.toml 文件，阐述如何去构建这些 crate。Cargo 实际上就是一个包，它包含了用于构建你代码的命令行工具的二进制 crate。其他项目也依赖 Cargo 库来实现与 Cargo 命令行程序一样的逻辑。

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

让我们来看看创建包的时候会发生什么。首先，我们输入命令 cargo new my-project：

1
2
3
4
5
6
7

$ 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 给我们创建了什么，Cargo 会给我们的包创建一个 Cargo.toml 文件。查看 Cargo.toml 的内容，会发现并没有提到 src/main.rs，**因为 Cargo 遵循的一个约定：src/main.rs 就是一个与包同名的二进制 crate 的 crate 根。**同样的，Cargo 知道如果包目录中包含 src/lib.rs，则包带有与其同名的库 crate，且 src/lib.rs 是 crate 根。crate 根文件将由 Cargo 传递给 rustc 来实际构建库或者二进制项目。

1
2
3
4
5
6
7
8
9
10

[package]
name = "Functions"
version = "0.1.0"
edition = "2024"

[dependencies]
//假如我们要添加main跟lib之外的其他依赖
[[bin]]
name = "another-app" # 这是你希望这个额外二进制 crate 的名称
path = "src/bin/another_app.rs" # 这是它的源文件路径

在此，我们有了一个只包含 src/main.rs 的包，意味着它只含有一个名为 my-project 的二进制 crate。如果一个包同时含有 src/main.rs 和 src/lib.rs，则它有两个 crate：一个二进制的和一个库的，且名字都与包相同。通过将文件放在 src/bin 目录下，一个包可以拥有多个二进制 crate：每个 src/bin 下的文件都会被编译成一个独立的二进制 crate。

来点人话

单一二进制 Crate

最简单的 Rust 包结构是一个只包含 src/main.rs 文件的包。在这种情况下，你的包将编译成一个名为 my-project 的二进制 crate（其中 my-project 是你的包名）。所有代码都将包含在 main.rs 文件中。

1
2
3
4

my-project/
├── src/
│   └── main.rs
└── Cargo.toml

二进制 Crate 和库 Crate 共存

如果一个包同时包含 src/main.rs 和 src/lib.rs，那么它将拥有两个 crate：一个二进制 crate 和一个库 crate。这两个 crate 的名字都默认与包名相同。

• src/main.rs 中的代码会编译成可执行程序。
• src/lib.rs 中的代码会编译成库，可以被其他项目（包括当前包的二进制 crate）引用。

1
2
3
4
5

my-project/
├── src/
│   ├── main.rs
│   └── lib.rs
└── Cargo.toml

在这种结构中，main.rs 通常会使用 use my_project; 或 use crate;（在 Rust 2018 版及更高版本中）来引用 lib.rs 中定义的模块和函数。

多个二进制 Crate

Rust 包可以通过将文件放置在 src/bin 目录下拥有多个二进制 crate。src/bin 目录下的每个文件都会被编译成一个独立的二进制 crate。每个文件的名称（不包括 .rs 后缀）将成为对应二进制 crate 的名称。

1
2
3
4
5
6
7
8

my-project/
├── src/
│   ├── main.rs         // 默认的二进制 crate
│   ├── lib.rs          // 库 crate
│   └── bin/
│       ├── my_tool.rs  // 额外的二进制 crate: `my_tool`
│       └── another_app.rs // 额外的二进制 crate: `another_app`
└── Cargo.toml

在这个例子中：

• cargo run 默认会编译并运行 src/main.rs 对应的二进制 crate。

• 你可以使用 cargo run --bin my_tool 来运行 src/bin/my_tool.rs 对应的二进制 crate。

• 同样，cargo run --bin another_app 会运行 src/bin/another_app.rs。

  当 Rust 包包含多个二进制 crate 时，src/main.rs 中的内容仍然是默认运行的二进制 crate。

  即使你在 src/bin 目录下添加了其他的 .rs 文件来创建额外的二进制 crate，cargo run 命令在没有额外指定的情况下，依然会查找并运行 src/main.rs 编译而成的可执行文件。

  如果你想运行 src/bin 目录下特定的二进制 crate，你需要使用 cargo run --bin <crate-name> 命令，其中 <crate-name> 是你想要运行的二进制 crate 的文件名（不包括 .rs 后缀）。

  举个例子：

  假设你有这样的项目结构：

  1 2 3 4 5 6

  my-project/ ├── src/ │ ├── main.rs // 默认的二进制 crate │ └── bin/ │ └── my_tool.rs // 另一个二进制 crate: `my_tool` └── Cargo.toml

  • 运行 cargo run 会编译并执行 src/main.rs 中的代码。
  • 运行 cargo run --bin my_tool 则会编译并执行 src/bin/my_tool.rs 中的代码。

  所以，src/main.rs 就像是你的项目主要的或默认的入口点，而 src/bin 中的文件则提供了额外的、可独立运行的工具或应用程序。

  暂时不知道有什么用

模块的组织

在上述基本结构的基础上，你可以在 src 目录下创建子目录来进一步组织你的模块。每个 mod.rs 文件或与目录同名的 .rs 文件（例如 my_module/mod.rs 或 my_module.rs）都代表一个模块。

例如，如果你在 src/lib.rs 中有一个复杂的库，你可以将其拆分为多个文件和目录：

1
2
3
4
5
6
7
8
9
10
11

my-project/
├── src/
│   ├── main.rs
│   └── lib.rs
│   │   // lib.rs 的内容可能包含 `mod data;` 和 `mod utils;`
│   ├── data/          // 对应 `data` 模块
│   │   ├── mod.rs     // data 模块的根文件
│   │   └── processing.rs // data 模块下的子模块 `processing`
│   └── utils/         // 对应 `utils` 模块
│       └── mod.rs     // utils 模块的根文件
└── Cargo.toml

在这种结构中：

• src/lib.rs 可以通过 mod data; 和 mod utils; 声明并引入 data 和 utils 模块。
• src/data/mod.rs 是 data 模块的入口点，它可以通过 mod processing; 声明 processing 子模块。

总结来说，Rust 的文件目录结构和模块系统紧密配合，主要遵循以下原则：

• src/main.rs: 默认的二进制 crate 入口。
• src/lib.rs: 默认的库 crate 入口。
• src/bin/ 目录: 用于存放额外的二进制 crate。
• 子目录和 mod.rs (或与目录同名的 .rs 文件): 用于组织更复杂的模块结构。

理解这些约定将帮助你有效地组织和管理你的 Rust 项目，无论它们是简单的工具还是大型的应用程序。

Crate 根是什么东西？

在 Rust 里，Crate 根 (Crate Root) 可以理解为你整个 Rust 项目（或者说一个 Crate）的“总入口文件”。当 Rust 编译器开始编译你的代码时，它就是从这个文件开始读起，然后根据里面的声明，一步步地找到并包含你项目里所有其他的模块和代码。

可以把它想象成一本书的“扉页”或者一个网站的“首页”。

Crate 根在哪里？

Crate 根文件的位置是约定俗成的：

1. 对于一个库 Crate (Library Crate)：
   • 它的 Crate 根文件是 src/lib.rs。
   • 这样的 Crate 编译出来的是一个库（就像一个工具箱，提供很多功能给其他代码使用），而不是一个独立运行的程序。
2. 对于一个二进制 Crate (Binary Crate)：
   • 它的 Crate 根文件是 src/main.rs。
   • 这样的 Crate 编译出来的是一个可执行程序（就像一个应用程序，可以直接运行）。

Crate 根的作用是什么？

Crate 根文件主要有以下几个作用：

• 编译起点：编译器总是从这里开始扫描和解析你的代码。
• 模块声明：你会在 Crate 根文件中使用 mod 关键字来声明你 Crate 中所有顶级的模块。比如，在 src/main.rs 中写 mod garden;，就是告诉编译器：“我有一个叫做 garden 的模块，请去 src/garden.rs 或 src/garden/mod.rs 找到它的代码。”
• 公共接口（对于库 Crate）：如果你的 Crate 是一个库，src/lib.rs 就定义了这个库向外部暴露的公共 API。其他项目在使用你的库时，会通过这个文件来访问你的功能。
• 程序入口（对于二进制 Crate）：如果你的 Crate 是一个二进制程序，src/main.rs 中的 fn main() 函数就是程序执行的起点。

简单来说：

Crate 根就是你的 Rust 项目（一个 Crate）的“大脑”或者“指挥中心”，它告诉编译器如何找到并组织你所有的代码。没有它，编译器就不知道从何开始构建你的程序或库。

官方文档依旧不说人话

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

在本节，我们将讨论模块和其它一些关于模块系统的部分，如允许你命名项的 路径（paths）；用来将路径引入作用域的 use 关键字；以及使项变为公有的 pub 关键字。我们还将讨论 as 关键字、外部包（external packages）和 glob 运算符（glob operator）。

首先，我们将从一系列的规则开始，在你未来组织代码的时候，这些规则可被用作简单的参考。接下来我们将会详细的解释每条规则。

模块小抄（Cheat Sheet）

在深入了解模块和路径的细节之前，这里提供一个简单的参考，用来解释模块、路径、use关键词和pub关键词如何在编译器中工作，以及大部分开发者如何组织他们的代码。我们将在本章中举例说明每条规则，但这是回顾模块工作原理的绝佳参考。

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

• 声明模块

  : 在 crate 根文件中，你可以声明一个新模块；比如，用

  1	mod garden;

  声明了一个叫做

  1

  garden

  的模块。编译器会在下列路径中寻找模块代码：

  • 内联，用大括号替换 mod garden 后跟的分号

• 在文件 src/garden.rs

  • 在文件 src/garden/mod.rs

• 声明子模块

  : 在除了 crate 根节点以外的任何文件中，你可以定义子模块。比如，你可能在src/garden.rs 中声明

  1	mod vegetables;

  。编译器会在以父模块命名的目录中寻找子模块代码：

  • 内联，直接在 mod vegetables 后方不是一个分号而是一个大括号

• 在文件 src/garden/vegetables.rs

  • 在文件 src/garden/vegetables/mod.rs

• 模块中的代码路径: 一旦一个模块是你 crate 的一部分，你可以在隐私规则允许的前提下，从同一个 crate 内的任意地方，通过代码路径引用该模块的代码。举例而言，一个 garden vegetables 模块下的 Asparagus 类型可以通过 crate::garden::vegetables::Asparagus 访问。

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

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

这里我们创建一个名为backyard的二进制 crate 来说明这些规则。该 crate 的路径同样命名为backyard，该路径包含了这些文件和目录：

1
2
3
4
5
6
7
8

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

这个例子中的 crate 根文件是 src/main.rs，该文件包含了：

文件名：src/main.rs

1
2
3
4
5
6
7
8

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

pub mod garden;

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

pub mod garden; 行告诉编译器将 src/garden.rs 中发现的代码包含进来：

文件名：src/garden.rs

1

pub mod vegetables;

在此处，pub mod vegetables; 意味着在 src/garden/vegetables.rs 中的代码也应该被包含。这些代码是：

1
2

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

现在让我们深入了解这些规则的细节并在实践中演示它们！

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

模块让我们可以将一个 crate 中的代码进行分组，以提高可读性与重用性。因为一个模块中的代码默认是私有的，所以还可以利用模块控制项的私有性（privacy）。私有项是不可为外部使用的内在详细实现。我们也可以将模块和它其中的项标记为公开的，这样，外部代码就可以使用并依赖于它们。

作为示例，让我们编写一个提供餐厅功能的库 crate。我们将定义函数的签名，但将其函数体留空以便将注意力集中在代码的组织结构上而不是餐厅实现的细节。

在餐饮业，餐馆中会有一些地方被称之为前台（front of house），还有另外一些地方被称之为后台（back of house）。前台是招待顾客的地方；这包括接待员为顾客安排座位、服务员接受点单和付款、调酒师制作饮品的地方。后台则是厨师和烹饪人员在厨房工作、洗碗工清理餐具，以及经理处理行政事务的区域。

为了以这种方式构建我们的 crate，我们可以将其功能组织到嵌套模块中。通过执行 cargo new restaurant --lib 来创建一个新的名为 restaurant 的库。然后将示例 7-1 中所罗列出来的代码放入 src/lib.rs 中，来定义一些模块和函数签名；这段代码即为前台部分。

1
2
3
4
5
6
7
8
9
10
11
12

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

示例 7-1：一个包含了其他内置了函数的模块的 front_of_house 模块

我们使用 mod 关键字来定义模块，后跟模块名（本例中叫做 front_of_house），并且用花括号包围模块的主体。在模块内，我们还可以定义其它的模块，就像本例中的 hosting 和 serving 模块。模块还可以保存一些定义的其它项，比如结构体、枚举、常量、trait、或者如示例 7-1 所示的函数。

通过使用模块，我们可以将相关的定义分组到一起，并指出它们为什么相关。程序员可以通过使用这段代码，更加容易地找到他们想要的定义，因为他们可以基于分组来对代码进行导航，而不需要阅读所有的定义。程序员向这段代码中添加一个新的功能时，他们也会知道代码应该放置在何处，可以保持程序的组织性。

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

示例 7-2 展示了示例 7-1 中模块树的结构。

1
2
3
4
5
6
7
8
9

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

示例 7-2: 示例 7-1 中代码的模块树

这个树展示了一些模块是如何被嵌入到另一个模块的（例如，hosting 嵌套在 front_of_house 中）。这个树还展示了一些模块是互为兄弟（siblings）的，这意味着它们定义在同一模块中；hosting 和 serving 被一起定义在 front_of_house 中。继续沿用家庭关系的比喻，如果一个模块 A 被包含在模块 B 中，我们将模块 A 称为模块 B 的 子（child）模块，模块 B 则是模块 A 的 父（parent）模块。注意，整个模块树都植根于名为 crate 的隐式模块下。

这个模块树可能会令你想起电脑上文件系统的目录树；这是一个非常恰当的类比！就像文件系统的目录，你可以使用模块来组织你的代码。并且，就像目录中的文件，我们需要一种方法来找到模块。

上面这段话多少看的人有点懵逼,我们现在让AI来说点人话

1. Rust 代码的起点：从“大门”开始找

你的整个 Rust 项目，无论多大，都有一个固定的“大门”。

• 如果你写的是一个可执行程序（像一个 .exe 文件），大门通常是 src/main.rs。
• 如果你写的是一个库（给别人用的代码包），大门就是 src/lib.rs。

编译器盖房子时，第一步就是从这个“大门”开始，一步步往里找代码。

2. 声明模块：给你的代码分房间

就像家里有客厅、卧室、厨房一样，你的代码也需要分门别类。在“大门”文件里（比如 src/main.rs），你可以用 mod 房间名; 来声明一个新的“房间”。

比如：mod garden;

这告诉编译器：“嘿，我有一个叫 garden 的房间！” 编译器就会去以下几个地方找这个房间的具体图纸：

• 直接在大括号里： 你可以直接在 mod garden 后面跟一对 {}，把所有代码写在里面，就像一个“开放式厨房”。
• 在同级文件里： 编译器会去 src/garden.rs 这个文件里找。
• 在同级文件夹里： 编译器会去 src/garden/mod.rs 这个文件里找（mod.rs 文件就像这个文件夹的“总说明书”）。

3. 声明子模块：房间里再隔小间

如果你的“房间”里内容太多，还可以再隔出“小间”。比如，你已经在 src/garden.rs（也就是 garden 房间的图纸）里，想再分一个 vegetables 的“小间”。

你可以写：mod vegetables;

这时，编译器就知道要去 garden 这个“房间”里找 vegetables 这个“小间”的图纸了。它会去：

• 直接在大括号里： 和上面一样，可以直接写在大括号里。
• 在父房间的子文件夹里： 编译器会去 src/garden/vegetables.rs 这个文件里找。
• 在父房间的子文件夹里的 mod.rs 文件： 编译器会去 src/garden/vegetables/mod.rs 这个文件里找。

4. 模块中的代码路径：怎么找到某个东西？

想象你在一个大房子里，要描述某个东西在哪儿。你会说“在客厅里沙发的旁边”。在 Rust 里，你要引用一个模块里的东西，也需要指明它的“路径”。

比如，如果你有个叫 Asparagus 的类型，它在 garden 房间的 vegetables 小间里，那么它的完整路径就是： crate::garden::vegetables::Asparagus

• crate:: 就代表你这个项目的根目录（也就是那个“大门”）。
• 后面跟着的就是模块一层层嵌套的名字。

5. 私有 vs 公用：谁能看到我的东西？

这是关于隐私的规则：

• 默认是私有的： 你在一个模块里写的东西，默认只有这个模块自己能用，外面是看不到的。就像你卧室里的东西，客厅里的人看不到。
• pub mod 公开模块： 如果你想让整个 garden 房间都能被外面的人看到，你需要在声明它的时候加上 pub，写成 pub mod garden;。
• pub 公开模块内部成员： 即使一个房间是公开的，里面的家具（比如结构体、函数）默认还是私有的。如果你想让 Asparagus 这个“家具”也能被外面看到，你也要在它前面加上 pub。

6. use 关键字：走捷径，少写路名！

想象你每次去厨房都要说“去客厅，然后穿过餐厅，再到厨房”。这太麻烦了！

use 关键字就是用来走捷径的。比如：

1

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

这行代码就是告诉 Rust：“以后在这个地方，我提到 Asparagus，就直接指代 crate::garden::vegetables::Asparagus 这个东西，不用每次都写那么长一串路径了！”

这样，你以后在这个文件里直接写 Asparagus 就可以了，方便很多。

用 backyard 例子来说明：

现在，我们把上面的规则套到那个 backyard 项目里，就像搭建一个真实的小花园：

1. src/main.rs (主屋，程序的入口)：
   • pub mod garden;：主屋里声明了一个公开的 garden 房间（所以编译器去 src/garden.rs 里找这个房间的图纸）。
   • use crate::garden::vegetables::Asparagus;：这里设置了一个捷径！以后我直接写 Asparagus，就知道指的是 garden 房间里 vegetables 小间里的 Asparagus 这个植物。
   • fn main() { ... }：这是程序真正运行的地方，就像主屋里的客厅。它创建了一个 Asparagus 植物，并打印出来。
2. src/garden.rs (花园的图纸)：
   • pub mod vegetables;：花园里声明了一个公开的 vegetables 小间（所以编译器去 src/garden/vegetables.rs 里找这个小间的图纸）。
3. src/garden/vegetables.rs (蔬菜小间的图纸)：
   • pub struct Asparagus {}：这里定义了一个公开的 Asparagus 植物结构体。

通过这些规则，整个项目就被组织得井井有条，各个部分各司其职，又可以通过明确的路径相互引用。

src/garden.rs 不是一个独立的库 crate。它只是一个模块文件，是 backyard 这个二进制 crate 的一部分。

src/garden.rs 为什么不在 lib 目录下？

src/garden.rs 之所以直接放在 src 目录下，是因为它被 src/main.rs 中的 pub mod garden; 这行代码声明并包含了进来。

当你在 src/main.rs（或 src/lib.rs）中声明 mod garden; 时，Rust 编译器会按照你之前看到的规则去寻找 garden 模块的代码：

1. 在 src/garden.rs 文件中。
2. 在 src/garden/mod.rs 文件中。

在这个例子中，它找到了 src/garden.rs，并将其中的代码（包括它声明的 vegetables 模块）作为 main.rs 所属的这个二进制 crate 的一部分编译进去。所以，garden.rs 仅仅是 backyard 这个二进制 crate 内部的一个模块，用来组织代码。

那 lib 目录是干啥用的？

lib 目录（具体来说是 src/lib.rs 文件）是用来创建库 crate 的。

• 库 crate 是一种可以被其他项目（甚至是你自己项目的二进制 crate）引用和复用的代码包。它不直接生成可执行文件，而是生成一个库文件（例如 .rlib 文件）。
• 当你的项目包含 src/lib.rs 时，Cargo 会自动将其视为一个库 crate 的根文件。

区别在于：

• src/lib.rs：定义的是整个库 crate 的入口和结构，它是一个独立的编译单元，旨在被其他代码导入使用。
• src/garden.rs：定义的是当前二进制 crate（或库 crate）内部的一个模块，它只是用来组织该 crate 内部的代码，而不是一个独立的、可被其他外部项目直接引用的 crate。

简而言之：

src/lib.rs 相当于你的项目要对外提供的“工具箱”的“总说明书”。而 src/garden.rs 只是你这个工具箱（或你的主程序）内部的一个“抽屉”，用来存放相关工具。

为了更好地理解，我们再回顾一下 Rust 包中不同类型的 Crate 和模块文件的角色：

1. 默认二进制 Crate (src/main.rs):
   • 这是你运行 cargo run 时默认会编译和执行的程序。
   • 必须包含一个 fn main() 函数。
   • 它可以声明和使用内部的模块文件（比如本例中的 src/garden.rs），这些模块文件最终都成为了这个二进制 Crate 的一部分。
2. 库 Crate (src/lib.rs):
   • 这是为了提供可复用的代码库而存在的。它不包含 main 函数。
   • 编译后生成的是一个库文件（例如 .rlib 或 .so/.dll），而不是可执行文件。
   • 这个库 Crate 可以被其他项目（包括当前包的默认二进制 Crate src/main.rs 或其他位于 src/bin 目录下的二进制 Crate）引用和使用。
3. 额外二进制 Crate (src/bin/\*.rs):
   • 如果你的项目需要除了 src/main.rs 之外的其他独立可执行程序，你就会把它们放在 src/bin/ 目录下。
   • src/bin 目录下的每个 .rs 文件都会被编译成一个独立的二进制 Crate，并且每个文件都需要包含一个 fn main() 函数。
   • 例如，如果你有 src/bin/my_tool.rs，那么你可以用 cargo run --bin my_tool 来运行它。

当然可以。在这个餐厅项目中，你可以完全按照 Backyard 项目的模式来组织代码，将餐厅功能模块化，但不是作为一个独立的库 crate，而是作为主二进制 crate (src/main.rs) 的一部分来包含。

这意味着：

1. 没有 src/lib.rs 文件：你的项目将不会包含一个独立的库 crate。
2. src/main.rs 作为主入口：所有功能将最终通过 src/main.rs 来使用。
3. 模块文件直接在 src/ 目录下或其子目录中：像 src/garden.rs 在 Backyard 项目中一样，你可以在 src/ 目录下创建 restaurant_logic.rs 或者 front_of_house.rs 等文件，这些文件会通过 mod 声明被 src/main.rs 包含进来。