12.一个 I/O 项目：构建一个命令行程序

本章既是一个目前所学的很多技能的概括，也是一个更多标准库功能的探索。我们将构建一个与文件和命令行输入/输出交互的命令行工具来练习现在一些你已经掌握的 Rust 技能。

Rust 的运行速度、安全性、单二进制文件输出和跨平台支持使其成为创建命令行程序的绝佳选择，所以我们的项目将创建一个我们自己版本的经典命令行搜索工具：grep。grep 是 “Globally search a Regular Expression and Print.” 的首字母缩写。grep 最简单的使用场景是在特定文件中搜索指定字符串。为此，grep 获取一个文件路径和一个字符串作为参数，接着读取文件并找到其中包含字符串参数的行，然后打印出这些行。

在这个过程中，我们会展示如何让我们的命令行工具利用很多命令行工具中用到的终端功能。读取环境变量来使得用户可以配置工具的行为。打印到标准错误控制流（stderr）而不是标准输出（stdout），例如这样用户可以选择将成功输出重定向到文件中的同时仍然在屏幕上显示错误信息。

一位 Rust 社区的成员，Andrew Gallant，已经创建了一个功能完整且非常快速的 grep 版本，叫做 ripgrep。相比之下，我们的版本将非常简单，本章将教会你一些帮助理解像 ripgrep 这样真实项目的背景知识。

我们的 grep 项目将会结合之前所学的一些内容：

  • 代码组织（使用 第七章 学习的模块）
  • vector 和字符串（第八章，集合）
  • 错误处理（第九章）
  • 合理的使用 trait 和生命周期（第十章）
  • 测试（第十一章）

另外还会简要的讲到闭包、迭代器和 trait 对象，他们分别会在 第十三章 和 第十七章 中详细介绍。

12.1接受命令行参数

一如既往使用 cargo new 新建一个项目，我们称之为 minigrep 以便与可能已经安装在系统上的 grep 工具相区别：

$ cargo new minigrep Created binary (application) `minigrep` project$ cd minigrep

第一个任务是让 minigrep 能够接受两个命令行参数：文件路径和要搜索的字符串。也就是说我们希望能够使用 cargo run、要搜索的字符串和被搜索的文件的路径来运行程序，像这样：

$ cargo run -- searchstring example-filename.txt

现在 cargo new 生成的程序忽略任何传递给它的参数。Crates.io 上有一些现成的库可以帮助我们接受命令行参数，不过我们正在学习这些内容，让我们自己来实现一个。

读取参数值

为了确保 minigrep 能够获取传递给它的命令行参数的值，我们需要一个 Rust 标准库提供的函数 std::env::args。这个函数返回一个传递给程序的命令行参数的 迭代器（iterator）。我们会在 第十三章 全面的介绍它们。但是现在只需理解迭代器的两个细节：迭代器生成一系列的值，可以在迭代器上调用 collect 方法将其转换为一个集合，比如包含所有迭代器产生元素的 vector。

示例 12-1 中允许 minigrep 程序读取任何传递给它的命令行参数并将其收集到一个 vector 中。

文件名：src/main.rs

use std::env;fn main() {let args: Vec<String> = env::args().collect();dbg!(args);}

示例 12-1：将命令行参数收集到一个 vector 中并打印出来

首先使用 use 语句来将 std::env 模块引入作用域以便可以使用它的 args 函数。注意 std::env::args 函数被嵌套进了两层模块中。正如 第七章 讲到的，当所需函数嵌套了多于一层模块时，通常将父模块引入作用域，而不是其自身。这便于我们利用 std::env 中的其他函数。这比增加了 use std::env::args; 后仅仅使用 args 调用函数要更明确一些，因为 args 容易被错认成一个定义于当前模块的函数。

[args 函数和无效的 Unicode]

注意 std::env::args 在其任何参数包含无效 Unicode 字符时会 panic。如果你需要接受包含无效 Unicode 字符的参数，使用 std::env::args_os 代替。这个函数返回 OsString 值而不是 String 值。这里出于简单考虑使用了 std::env::args，因为 OsString 值每个平台都不一样而且比 String 值处理起来更为复杂。

在 main 函数的第一行，我们调用了 env::args，并立即使用 collect 来创建了一个包含迭代器所有值的 vector。collect 可以被用来创建很多类型的集合，所以这里显式注明 args 的类型来指定我们需要一个字符串 vector。虽然在 Rust 中我们很少会需要注明类型，然而 collect 是一个经常需要注明类型的函数，因为 Rust 不能推断出你想要什么类型的集合。

最后，我们使用调试宏打印出 vector。让我们尝试分别用两种方式（不包含参数和包含参数）运行代码：

$ cargo run Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 0.61s Running `target/debug/minigrep`[src/main.rs:5] args = ["target/debug/minigrep",]$ cargo run -- needle haystack Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 1.57s Running `target/debug/minigrep needle haystack`[src/main.rs:5] args = ["target/debug/minigrep","needle","haystack",]

注意 vector 的第一个值是 "target/debug/minigrep"，它是我们二进制文件的名称。这与 C 中的参数列表的行为相匹配，让程序使用在执行时调用它们的名称。如果要在消息中打印它或者根据用于调用程序的命令行别名更改程序的行为，通常可以方便地访问程序名称，不过考虑到本章的目的，我们将忽略它并只保存所需的两个参数。

将参数值保存进变量

目前程序可以访问指定为命令行参数的值。现在需要将这两个参数的值保存进变量这样就可以在程序的余下部分使用这些值了。让我们如示例 12-2 这样做：

文件名：src/main.rs

use std::env;fn main() {let args: Vec<String> = env::args().collect();let query = &args[1];let file_path = &args[2];println!("Searching for {}", query);println!("In file {}", file_path);}

示例 12-2：创建变量来存放查询参数和文件路径参数

正如之前打印出 vector 时所所看到的，程序的名称占据了 vector 的第一个值 args[0]，所以我们从索引为 1 的参数开始。minigrep 获取的第一个参数是需要搜索的字符串，所以将其将第一个参数的引用存放在变量 query 中。第二个参数将是文件路径，所以将第二个参数的引用放入变量 file_path 中。

我们将临时打印出这些变量的值来证明代码如我们期望的那样工作。使用参数 test 和 sample.txt 再次运行这个程序：

$ cargo run -- test sample.txt Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 0.0s Running `target/debug/minigrep test sample.txt`Searching for testIn file sample.txt

好的，它可以工作！我们将所需的参数值保存进了对应的变量中。之后会增加一些错误处理来应对类似用户没有提供参数的情况，不过现在我们将忽略他们并开始增加读取文件功能。

12.2读取文件

现在我们要增加读取由 file_path 命令行参数指定的文件的功能。首先，需要一个用来测试的示例文件：我们会用一个拥有多行少量文本且有一些重复单词的文件。示例 12-3 是一首艾米莉·狄金森（Emily Dickinson）的诗，它正适合这个工作！在项目根目录创建一个文件 poem.txt，并输入诗 “I’m nobody! Who are you?”：

文件名：poem.txt

I'm nobody! Who are you?Are you nobody, too?Then there's a pair of us - don't tell!They'd banish us, you know.How dreary to be somebody!How public, like a frogTo tell your name the livelong dayTo an admiring bog!

示例 12-3：艾米莉·狄金森的诗 “I’m nobody! Who are you?”，一个好的测试用例

创建完这个文件之后，修改 src/main.rs 并增加如示例 12-4 所示的打开文件的代码：

文件名：src/main.rs

use std::env;use std::fs;fn main() {// --snip--println!("In file {}", file_path);let contents = fs::read_to_string(file_path).expect("Should have been able to read the file");println!("With text:\n{contents}");}

示例 12-4：读取第二个参数所指定的文件内容

首先，我们增加了一个 use 语句来引入标准库中的相关部分：我们需要 std::fs 来处理文件。

在 main 中新增了一行语句：fs::read_to_string 接受 file_path，打开文件，接着返回包含其内容的 std::io::Result。

在这些代码之后，我们再次增加了临时的 println! 打印出读取文件之后 contents 的值，这样就可以检查目前为止的程序能否工作。

尝试运行这些代码，随意指定一个字符串作为第一个命令行参数（因为还未实现搜索功能的部分）而将 poem.txt 文件将作为第二个参数：

$ cargo run -- the poem.txt Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 0.0s Running `target/debug/minigrep the poem.txt`Searching for theIn file poem.txtWith text:I'm nobody! Who are you?Are you nobody, too?Then there's a pair of us - don't tell!They'd banish us, you know.How dreary to be somebody!How public, like a frogTo tell your name the livelong dayTo an admiring bog!

好的！代码读取并打印出了文件的内容。虽然它还有一些瑕疵：此时 main 函数有着多个职能，通常函数只负责一个功能的话会更简洁并易于维护。另一个问题是没有尽可能的处理错误。虽然我们的程序还很小，这些瑕疵并不是什么大问题，不过随着程序功能的丰富，将会越来越难以用简单的方法修复他们。在开发程序时，及早开始重构是一个最佳实践，因为重构少量代码时要容易的多，所以让我们现在就开始吧。

12.3重构改进模块性和错误处理

为了改善我们的程序这里有四个问题需要修复，而且他们都与程序的组织方式和如何处理潜在错误有关。第一，main 现在进行了两个任务：它解析了参数并打开了文件。对于一个这样的小函数，这并不是一个大问题。然而如果 main 中的功能持续增加，main 函数处理的独立任务也会增加。当函数承担了更多责任，它就更难以推导，更难以测试，并且更难以在不破坏其他部分的情况下做出修改。最好能分离出功能以便每个函数就负责一个任务。

这同时也关系到第二个问题：query 和 file_path 是程序中的配置变量，而像 contents 则用来执行程序逻辑。随着 main 函数的增长，就需要引入更多的变量到作用域中，而当作用域中有更多的变量时，将更难以追踪每个变量的目的。最好能将配置变量组织进一个结构，这样就能使他们的目的更明确了。

第三个问题是如果打开文件失败我们使用 expect 来打印出错误信息，不过这个错误信息只是说 Should have been able to read the file。读取文件失败的原因有多种：例如文件不存在，或者没有打开此文件的权限。目前，无论处于何种情况，我们只是打印出“文件读取出现错误”的信息，这并没有给予使用者具体的信息！

第四，我们不停地使用 expect 来处理不同的错误，如果用户没有指定足够的参数来运行程序，他们会从 Rust 得到 index out of bounds 错误，而这并不能明确地解释问题。如果所有的错误处理都位于一处，这样将来的维护者在需要修改错误处理逻辑时就只需要考虑这一处代码。将所有的错误处理都放在一处也有助于确保我们打印的错误信息对终端用户来说是有意义的。

让我们通过重构项目来解决这些问题。

二进制项目的关注分离

main 函数负责多个任务的组织问题在许多二进制项目中很常见。所以 Rust 社区开发出一类在 main 函数开始变得庞大时进行二进制程序的关注分离的指导。这些过程有如下步骤：

  • 将程序拆分成 main.rs 和 lib.rs 并将程序的逻辑放入 lib.rs 中。
  • 当命令行解析逻辑比较小时，可以保留在 main.rs 中。
  • 当命令行解析开始变得复杂时，也同样将其从 main.rs 提取到 lib.rs 中。

经过这些过程之后保留在 main 函数中的责任应该被限制为：

  • 使用参数值调用命令行解析逻辑
  • 设置任何其他的配置
  • 调用 lib.rs 中的 run 函数
  • 如果 run 返回错误，则处理这个错误

这个模式的一切就是为了关注分离：main.rs 处理程序运行，而 lib.rs 处理所有的真正的任务逻辑。因为不能直接测试 main 函数，这个结构通过将所有的程序逻辑移动到 lib.rs 的函数中使得我们可以测试他们。仅仅保留在 main.rs 中的代码将足够小以便阅读就可以验证其正确性。让我们遵循这些步骤来重构程序。

提取参数解析器

首先，我们将解析参数的功能提取到一个 main 将会调用的函数中，为将命令行解析逻辑移动到 src/lib.rs 中做准备。示例 12-5 中展示了新 main 函数的开头，它调用了新函数 parse_config。目前它仍将定义在 src/main.rs 中：

文件名：src/main.rs

fn main() {let args: Vec<String> = env::args().collect();let (query, file_path) = parse_config(&args);// --snip--}fn parse_config(args: &[String]) -> (&str, &str) {let query = &args[1];let file_path = &args[2];(query, file_path)}

示例 12-5：从 main 中提取出 parse_config 函数

我们仍然将命令行参数收集进一个 vector，不过不同于在 main 函数中将索引 1 的参数值赋值给变量 query 和将索引 2 的值赋值给变量 file_path，我们将整个 vector 传递给 parse_config 函数。接着 parse_config 函数将包含决定哪个参数该放入哪个变量的逻辑，并将这些值返回到 main。仍然在 main 中创建变量 query 和 file_path，不过 main 不再负责处理命令行参数与变量如何对应。

这对重构我们这小程序可能有点大材小用，不过我们将采用小的、增量的步骤进行重构。在做出这些改变之后，再次运行程序并验证参数解析是否仍然正常。经常验证你的进展是一个好习惯，这样在遇到问题时能帮助你定位问题的成因。

组合配置值

我们可以采取另一个小的步骤来进一步改善这个函数。现在函数返回一个元组，不过立刻又将元组拆成了独立的部分。这是一个我们可能没有进行正确抽象的信号。

另一个表明还有改进空间的迹象是 parse_config 名称的 config 部分，它暗示了我们返回的两个值是相关的并都是一个配置值的一部分。目前除了将这两个值组合进元组之外并没有表达这个数据结构的意义：我们可以将这两个值放入一个结构体并给每个字段一个有意义的名字。这会让未来的维护者更容易理解不同的值如何相互关联以及他们的目的。

注意：一些同学将这种在复杂类型更为合适的场景下使用基本类型的反模式称为 基本类型偏执（primitive obsession）。

示例 12-6 展示了 parse_config 函数的改进。

文件名：src/main.rs

fn main() {let args: Vec<String> = env::args().collect();let config = parse_config(&args);println!("Searching for {}", config.query);println!("In file {}", config.file_path);let contents = fs::read_to_string(config.file_path).expect("Should have been able to read the file");// --snip--}struct Config {query: String,file_path: String,}fn parse_config(args: &[String]) -> Config {let query = args[1].clone();let file_path = args[2].clone();Config { query, file_path }}

示例 12-6：重构 parse_config 返回一个 Config 结构体实例

新定义的结构体 Config 中包含字段 query 和 file_path。 parse_config 的签名表明它现在返回一个 Config 值。在之前的 parse_config 函数体中，我们返回了引用 args 中 String 值的字符串 slice，现在我们定义 Config 来包含拥有所有权的 String 值。main 中的 args 变量是参数值的所有者并只允许 parse_config 函数借用他们，这意味着如果 Config 尝试获取 args 中值的所有权将违反 Rust 的借用规则。

还有许多不同的方式可以处理 String 的数据，而最简单但有些不太高效的方式是调用这些值的 clone 方法。这会生成 Config 实例可以拥有的数据的完整拷贝，不过会比储存字符串数据的引用消耗更多的时间和内存。不过拷贝数据使得代码显得更加直白因为无需管理引用的生命周期，所以在这种情况下牺牲一小部分性能来换取简洁性的取舍是值得的。

使用 clone 的权衡取舍

由于其运行时消耗，许多 Rustacean 之间有一个趋势是倾向于避免使用 clone 来解决所有权问题。在关于迭代器的第十三章中，我们将会学习如何更有效率的处理这种情况，不过现在，复制一些字符串来取得进展是没有问题的，因为只会进行一次这样的拷贝，而且文件路径和要搜索的字符串都比较短。在第一轮编写时拥有一个可以工作但有点低效的程序要比尝试过度优化代码更好一些。随着你对 Rust 更加熟练，将能更轻松的直奔合适的方法，不过现在调用 clone 是完全可以接受的。

我们更新 main 将 parse_config 返回的 Config 实例放入变量 config 中，并将之前分别使用 query 和 file_path 变量的代码更新为现在的使用 Config 结构体的字段的代码。

现在代码更明确的表现了我们的意图，query 和 file_path 是相关联的并且他们的目的是配置程序如何工作。任何使用这些值的代码就知道在 config 实例中对应目的的字段名中寻找他们。

创建一个 Config 的构造函数

目前为止，我们将负责解析命令行参数的逻辑从 main 提取到了 parse_config 函数中，这有助于我们看清值 query 和 file_path 是相互关联的并应该在代码中表现这种关系。接着我们增加了 Config 结构体来描述 query 和 file_path 的相关性，并能够从 parse_config 函数中将这些值的名称作为结构体字段名称返回。

所以现在 parse_config 函数的目的是创建一个 Config 实例，我们可以将 parse_config 从一个普通函数变为一个叫做 new 的与结构体关联的函数。做出这个改变使得代码更符合习惯：可以像标准库中的 String 调用 String::new 来创建一个该类型的实例那样，将 parse_config 变为一个与 Config 关联的 new 函数。示例 12-7 展示了需要做出的修改：

文件名：src/main.rs

fn main() {let args: Vec<String> = env::args().collect();let config = Config::new(&args);// --snip--}// --snip--impl Config {fn new(args: &[String]) -> Config {let query = args[1].clone();let file_path = args[2].clone();Config { query, file_path }}}

示例 12-7：将 parse_config 变为 Config::new

这里将 main 中调用 parse_config 的地方更新为调用 Config::new。我们将 parse_config 的名字改为 new 并将其移动到 impl 块中，这使得 new 函数与 Config 相关联。再次尝试编译并确保它可以工作。

修复错误处理

现在我们开始修复错误处理。回忆一下之前提到过如果 args vector 包含少于 3 个项并尝试访问 vector 中索引 1 或索引 2 的值会造成程序 panic。尝试不带任何参数运行程序；这将看起来像这样：

$ cargo run Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 0.0s Running `target/debug/minigrep`thread 'main' panicked at 'index out of bounds: the len is 1 but the index is 1', src/main.rs:27:21note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

index out of bounds: the len is 1 but the index is 1 是一个针对程序员的错误信息，然而这并不能真正帮助终端用户理解发生了什么和他们应该做什么。现在就让我们修复它吧。

改善错误信息

在示例 12-8 中，在 new 函数中增加了一个检查在访问索引 1 和 2 之前检查 slice 是否足够长。如果 slice 不够长，程序会打印一个更好的错误信息并 panic：

文件名：src/main.rs

// --snip--fn new(args: &[String]) -> Config {if args.len() < 3 {panic!("not enough arguments");}// --snip--

示例 12-8：增加一个参数数量检查

这类似于 示例 9-13 中的 Guess::new 函数，那里如果 value 参数超出了有效值的范围就调用 panic!。不同于检查值的范围，这里检查 args 的长度至少是 3，而函数的剩余部分则可以在假设这个条件成立的基础上运行。如果 args 少于 3 个项，则这个条件将为真，并调用 panic! 立即终止程序。

有了 new 中这几行额外的代码，再次不带任何参数运行程序并看看现在错误看起来像什么：

$ cargo run Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 0.0s Running `target/debug/minigrep`thread 'main' panicked at 'not enough arguments', src/main.rs:26:13note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

这个输出就好多了，现在有了一个合理的错误信息。然而，还是有一堆额外的信息我们不希望提供给用户。所以在这里使用示例 9-9 中的技术可能不是最好的；正如 第九章 所讲到的一样，panic! 的调用更趋向于程序上的问题而不是使用上的问题。相反我们可以使用第九章学习的另一个技术 —— 返回一个可以表明成功或错误的 Result。

从 new 中返回 Result 而不是调用 panic!

我们可以选择返回一个 Result 值，它在成功时会包含一个 Config 的实例，而在错误时会描述问题。我们还将把函数名从new改为build，因为许多程序员希望 new 函数永远不会失败。当 Config::new 与 main 交流时，可以使用 Result 类型来表明这里存在问题。接着修改 main 将 Err 成员转换为对用户更友好的错误，而不是 panic! 调用产生的关于 thread 'main' 和 RUST_BACKTRACE 的文本。

示例 12-9 展示了为了返回 Result 在 Config::new 的返回值和函数体中所需的改变。注意这还不能编译，直到下一个示例同时也更新了 main 之后。

文件名：src/main.rs

impl Config {fn build(args: &[String]) -> Result<Config, &'static str> {if args.len() < 3 {return Err("not enough arguments");}let query = args[1].clone();let file_path = args[2].clone();Ok(Config { query, file_path })}}

示例 12-9：从 Config::build 中返回 Result

现在 build 函数返回一个 Result，在成功时带有一个 Config 实例而在出现错误时带有一个 &'static str。回忆一下第十章 “静态生命周期” 中讲到 &'static str 是字符串字面值的类型，也是目前的错误信息。

new 函数体中有两处修改：当没有足够参数时不再调用 panic!，而是返回 Err 值。同时我们将 Config 返回值包装进 Ok 成员中。这些修改使得函数符合其新的类型签名。

通过让 Config::build 返回一个 Err 值，这就允许 main 函数处理 new 函数返回的 Result 值并在出现错误的情况更明确的结束进程。

Config::build 调用并处理错误

为了处理错误情况并打印一个对用户友好的信息，我们需要像示例 12-10 那样更新 main 函数来处理现在 Config::build 返回的 Result。另外还需要手动实现原先由 panic!负责的工作，即以非零错误码退出命令行工具的工作。非零的退出状态是一个惯例信号，用来告诉调用程序的进程：该程序以错误状态退出了。

文件名：src/main.rs

use std::process;fn main() {let args: Vec<String> = env::args().collect();let config = Config::build(&args).unwrap_or_else(|err| {println!("Problem parsing arguments: {err}");process::exit(1);});// --snip--

示例 12-10：如果新建 Config 失败则使用错误码退出

在上面的示例中，使用了一个之前没有详细说明的方法：unwrap_or_else，它定义于标准库的 Result 上。使用 unwrap_or_else 可以进行一些自定义的非 panic! 的错误处理。当 Result 是 Ok 时，这个方法的行为类似于 unwrap：它返回 Ok 内部封装的值。然而，当其值是 Err 时，该方法会调用一个 闭包（closure），也就是一个我们定义的作为参数传递给 unwrap_or_else 的匿名函数。第十三章 会更详细的介绍闭包。现在你需要理解的是 unwrap_or_else 会将 Err 的内部值，也就是示例 12-9 中增加的 not enough arguments 静态字符串的情况，传递给闭包中位于两道竖线间的参数 err。闭包中的代码在其运行时可以使用这个 err 值。

我们新增了一个 use 行来从标准库中导入 process。在错误的情况闭包中将被运行的代码只有两行：我们打印出了 err 值，接着调用了 std::process::exit。process::exit 会立即停止程序并将传递给它的数字作为退出状态码。这类似于示例 12-8 中使用的基于 panic! 的错误处理，除了不会再得到所有的额外输出了。让我们试试：

$ cargo run Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 0.48s Running `target/debug/minigrep`Problem parsing arguments: not enough arguments

非常好！现在输出对于用户来说就友好多了。

从 main 提取逻辑

现在我们完成了配置解析的重构：让我们转向程序的逻辑。正如 “二进制项目的关注分离” 部分所展开的讨论，我们将提取一个叫做 run 的函数来存放目前 main 函数中不属于设置配置或处理错误的所有逻辑。一旦完成这些，main 函数将简明得足以通过观察来验证，而我们将能够为所有其他逻辑编写测试。

示例 12-11 展示了提取出来的 run 函数。目前我们只进行小的增量式的提取函数的改进。我们仍将在 src/main.rs 中定义这个函数：

文件名：src/main.rs

fn main() {// --snip--println!("Searching for {}", config.query);println!("In file {}", config.file_path);run(config);}fn run(config: Config) {let contents = fs::read_to_string(config.file_path).expect("Should have been able to read the file");println!("With text:\n{contents}");}// --snip--

示例 12-11：提取 run 函数来包含剩余的程序逻辑

现在 run 函数包含了 main 中从读取文件开始的剩余的所有逻辑。run 函数获取一个 Config 实例作为参数。

从 run 函数中返回错误

通过将剩余的逻辑分离进 run 函数而不是留在 main 中，就可以像示例 12-9 中的 Config::build 那样改进错误处理。不再通过 expect 允许程序 panic，run 函数将会在出错时返回一个 Result。这让我们进一步以一种对用户友好的方式统一 main 中的错误处理。示例 12-12 展示了 run 签名和函数体中的改变：

文件名：src/main.rs

use std::error::Error;// --snip--fn run(config: Config) -> Result<(), Box<dyn Error>> {let contents = fs::read_to_string(config.file_path)?;println!("With text:\n{contents}");Ok(())}

示例 12-12：修改 run 函数返回 Result

这里我们做出了三个明显的修改。首先，将 run 函数的返回类型变为 Result<(), Box>。之前这个函数返回 unit 类型 ()，现在它仍然保持作为 Ok 时的返回值。

对于错误类型，使用了 trait 对象 Box（在开头使用了 use 语句将 std::error::Error 引入作用域）。第十七章 会涉及 trait 对象。目前只需知道 Box 意味着函数会返回实现了 Error trait 的类型，不过无需指定具体将会返回的值的类型。这提供了在不同的错误场景可能有不同类型的错误返回值的灵活性。这也就是 dyn，它是 “动态的”（“dynamic”）的缩写。

第二个改变是去掉了 expect 调用并替换为 第九章 讲到的 ?。不同于遇到错误就 panic!，? 会从函数中返回错误值并让调用者来处理它。

第三个修改是现在成功时这个函数会返回一个 Ok 值。因为 run 函数签名中声明成功类型返回值是 ()，这意味着需要将 unit 类型值包装进 Ok 值中。Ok(()) 一开始看起来有点奇怪，不过这样使用 () 是惯用的做法，表明调用 run 函数只是为了它的副作用；函数并没有返回什么有意义的值。

上述代码能够编译，不过会有一个警告：

$ cargo run the poem.txt Compiling minigrep v0.1.0 (file:///projects/minigrep)warning: unused `Result` that must be used--> src/main.rs:19:5 |19 | run(config); | ^^^^^^^^^^^^ | = note: `#[warn(unused_must_use)]` on by default = note: this `Result` may be an `Err` variant, which should be handledwarning: `minigrep` (bin "minigrep") generated 1 warningFinished dev [unoptimized + debuginfo] target(s) in 0.71s Running `target/debug/minigrep the poem.txt`Searching for theIn file poem.txtWith text:I'm nobody! Who are you?Are you nobody, too?Then there's a pair of us - don't tell!They'd banish us, you know.How dreary to be somebody!How public, like a frogTo tell your name the livelong dayTo an admiring bog!

Rust 提示我们的代码忽略了 Result 值，它可能表明这里存在一个错误。但我们却没有检查这里是否有一个错误，而编译器提醒我们这里应该有一些错误处理代码！现在就让我们修正这个问题。

处理 main 中 run 返回的错误

我们将检查错误并使用类似示例 12-10 中 Config::build 处理错误的技术来处理他们，不过有一些细微的不同：

文件名：src/main.rs

fn main() {// --snip--println!("Searching for {}", config.query);println!("In file {}", config.file_path);if let Err(e) = run(config) {println!("Application error: {e}");process::exit(1);}}

我们使用 if let 来检查 run 是否返回一个 Err 值，不同于 unwrap_or_else，并在出错时调用 process::exit(1)。run 并不返回像 Config::build 返回的 Config 实例那样需要 unwrap 的值。因为 run 在成功时返回 ()，而我们只关心检测错误，所以并不需要 unwrap_or_else 来返回未封装的值，因为它只会是 ()。

不过两个例子中 if let 和 unwrap_or_else 的函数体都一样：打印出错误并退出。

将代码拆分到库 crate

现在我们的 minigrep 项目看起来好多了！现在我们将要拆分 src/main.rs 并将一些代码放入 src/lib.rs，这样就能测试他们并拥有一个含有更少功能的 main 函数。

让我们将所有不是 main 函数的代码从 src/main.rs 移动到新文件 src/lib.rs 中：

  • run 函数定义
  • 相关的 use 语句
  • Config 的定义
  • Config::build 函数定义

现在 src/lib.rs 的内容应该看起来像示例 12-13（为了简洁省略了函数体）。注意直到下一个示例修改完 src/main.rs 之后，代码还不能编译：

文件名：src/lib.rs

use std::error::Error;use std::fs;pub struct Config {pub query: String,pub file_path: String,}impl Config {pub fn build(args: &[String]) -> Result<Config, &'static str> {// --snip--}}pub fn run(config: Config) -> Result<(), Box<dyn Error>> {// --snip--}

示例 12-13：将 Config 和 run 移动到 src/lib.rs

这里使用了公有的 pub 关键字：在 Config、其字段和其 build 方法，以及 run 函数上。现在我们有了一个拥有可以测试的公有 API 的库 crate 了。

现在需要在 src/main.rs 中将移动到 src/lib.rs 的代码引入二进制 crate 的作用域中，如示例 12-14 所示：

文件名：src/main.rs

use std::env;use std::process;use minigrep::Config;fn main() {// --snip--if let Err(e) = minigrep::run(config) {// --snip--}}## 12.一个 I/O 项目：构建一个命令行程序本章既是一个目前所学的很多技能的概括，也是一个更多标准库功能的探索。我们将构建一个与文件和命令行输入/输出交互的命令行工具来练习现在一些你已经掌握的 Rust 技能。Rust 的运行速度、安全性、单二进制文件输出和跨平台支持使其成为创建命令行程序的绝佳选择，所以我们的项目将创建一个我们自己版本的经典命令行搜索工具：`grep`。grep 是 “**G**lobally search a **R**egular **E**xpression and **P**rint.” 的首字母缩写。`grep` 最简单的使用场景是在特定文件中搜索指定字符串。为此，`grep` 获取一个文件路径和一个字符串作为参数，接着读取文件并找到其中包含字符串参数的行，然后打印出这些行。在这个过程中，我们会展示如何让我们的命令行工具利用很多命令行工具中用到的终端功能。读取环境变量来使得用户可以配置工具的行为。打印到标准错误控制流（`stderr`）而不是标准输出（`stdout`），例如这样用户可以选择将成功输出重定向到文件中的同时仍然在屏幕上显示错误信息。一位 Rust 社区的成员，Andrew Gallant，已经创建了一个功能完整且非常快速的 `grep` 版本，叫做 `ripgrep`。相比之下，我们的版本将非常简单，本章将教会你一些帮助理解像 `ripgrep` 这样真实项目的背景知识。我们的 `grep` 项目将会结合之前所学的一些内容：- 代码组织（使用 [第七章](https://kaisery.github.io/trpl-zh-cn/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html) 学习的模块）- vector 和字符串（[第八章](https://kaisery.github.io/trpl-zh-cn/ch08-00-common-collections.html)，集合）- 错误处理（[第九章](https://kaisery.github.io/trpl-zh-cn/ch09-00-error-handling.html)）- 合理的使用 trait 和生命周期（[第十章](https://kaisery.github.io/trpl-zh-cn/ch10-00-generics.html)）- 测试（[第十一章](https://kaisery.github.io/trpl-zh-cn/ch11-00-testing.html)）另外还会简要的讲到闭包、迭代器和 trait 对象，他们分别会在 [第十三章](https://kaisery.github.io/trpl-zh-cn/ch13-00-functional-features.html) 和 [第十七章](https://kaisery.github.io/trpl-zh-cn/ch17-00-oop.html) 中详细介绍。### 12.1接受命令行参数一如既往使用 `cargo new` 新建一个项目，我们称之为 `minigrep` 以便与可能已经安装在系统上的 `grep` 工具相区别：```console$ cargo new minigrep Created binary (application) `minigrep` project$ cd minigrep

第一个任务是让 minigrep 能够接受两个命令行参数：文件路径和要搜索的字符串。也就是说我们希望能够使用 cargo run、要搜索的字符串和被搜索的文件的路径来运行程序，像这样：

$ cargo run -- searchstring example-filename.txt

现在 cargo new 生成的程序忽略任何传递给它的参数。Crates.io 上有一些现成的库可以帮助我们接受命令行参数，不过我们正在学习这些内容，让我们自己来实现一个。

读取参数值

为了确保 minigrep 能够获取传递给它的命令行参数的值，我们需要一个 Rust 标准库提供的函数 std::env::args。这个函数返回一个传递给程序的命令行参数的 迭代器（iterator）。我们会在 第十三章 全面的介绍它们。但是现在只需理解迭代器的两个细节：迭代器生成一系列的值，可以在迭代器上调用 collect 方法将其转换为一个集合，比如包含所有迭代器产生元素的 vector。

示例 12-1 中允许 minigrep 程序读取任何传递给它的命令行参数并将其收集到一个 vector 中。

文件名：src/main.rs

use std::env;fn main() {let args: Vec<String> = env::args().collect();dbg!(args);}

示例 12-1：将命令行参数收集到一个 vector 中并打印出来

首先使用 use 语句来将 std::env 模块引入作用域以便可以使用它的 args 函数。注意 std::env::args 函数被嵌套进了两层模块中。正如 第七章 讲到的，当所需函数嵌套了多于一层模块时，通常将父模块引入作用域，而不是其自身。这便于我们利用 std::env 中的其他函数。这比增加了 use std::env::args; 后仅仅使用 args 调用函数要更明确一些，因为 args 容易被错认成一个定义于当前模块的函数。

[args 函数和无效的 Unicode]

注意 std::env::args 在其任何参数包含无效 Unicode 字符时会 panic。如果你需要接受包含无效 Unicode 字符的参数，使用 std::env::args_os 代替。这个函数返回 OsString 值而不是 String 值。这里出于简单考虑使用了 std::env::args，因为 OsString 值每个平台都不一样而且比 String 值处理起来更为复杂。

在 main 函数的第一行，我们调用了 env::args，并立即使用 collect 来创建了一个包含迭代器所有值的 vector。collect 可以被用来创建很多类型的集合，所以这里显式注明 args 的类型来指定我们需要一个字符串 vector。虽然在 Rust 中我们很少会需要注明类型，然而 collect 是一个经常需要注明类型的函数，因为 Rust 不能推断出你想要什么类型的集合。

最后，我们使用调试宏打印出 vector。让我们尝试分别用两种方式（不包含参数和包含参数）运行代码：

$ cargo run Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 0.61s Running `target/debug/minigrep`[src/main.rs:5] args = ["target/debug/minigrep",]$ cargo run -- needle haystack Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 1.57s Running `target/debug/minigrep needle haystack`[src/main.rs:5] args = ["target/debug/minigrep","needle","haystack",]

注意 vector 的第一个值是 "target/debug/minigrep"，它是我们二进制文件的名称。这与 C 中的参数列表的行为相匹配，让程序使用在执行时调用它们的名称。如果要在消息中打印它或者根据用于调用程序的命令行别名更改程序的行为，通常可以方便地访问程序名称，不过考虑到本章的目的，我们将忽略它并只保存所需的两个参数。

将参数值保存进变量

目前程序可以访问指定为命令行参数的值。现在需要将这两个参数的值保存进变量这样就可以在程序的余下部分使用这些值了。让我们如示例 12-2 这样做：

文件名：src/main.rs

use std::env;fn main() {let args: Vec<String> = env::args().collect();let query = &args[1];let file_path = &args[2];println!("Searching for {}", query);println!("In file {}", file_path);}

示例 12-2：创建变量来存放查询参数和文件路径参数

正如之前打印出 vector 时所所看到的，程序的名称占据了 vector 的第一个值 args[0]，所以我们从索引为 1 的参数开始。minigrep 获取的第一个参数是需要搜索的字符串，所以将其将第一个参数的引用存放在变量 query 中。第二个参数将是文件路径，所以将第二个参数的引用放入变量 file_path 中。

我们将临时打印出这些变量的值来证明代码如我们期望的那样工作。使用参数 test 和 sample.txt 再次运行这个程序：

$ cargo run -- test sample.txt Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 0.0s Running `target/debug/minigrep test sample.txt`Searching for testIn file sample.txt

好的，它可以工作！我们将所需的参数值保存进了对应的变量中。之后会增加一些错误处理来应对类似用户没有提供参数的情况，不过现在我们将忽略他们并开始增加读取文件功能。

12.2读取文件

现在我们要增加读取由 file_path 命令行参数指定的文件的功能。首先，需要一个用来测试的示例文件：我们会用一个拥有多行少量文本且有一些重复单词的文件。示例 12-3 是一首艾米莉·狄金森（Emily Dickinson）的诗，它正适合这个工作！在项目根目录创建一个文件 poem.txt，并输入诗 “I’m nobody! Who are you?”：

文件名：poem.txt

I'm nobody! Who are you?Are you nobody, too?Then there's a pair of us - don't tell!They'd banish us, you know.How dreary to be somebody!How public, like a frogTo tell your name the livelong dayTo an admiring bog!

示例 12-3：艾米莉·狄金森的诗 “I’m nobody! Who are you?”，一个好的测试用例

创建完这个文件之后，修改 src/main.rs 并增加如示例 12-4 所示的打开文件的代码：

文件名：src/main.rs

use std::env;use std::fs;fn main() {// --snip--println!("In file {}", file_path);let contents = fs::read_to_string(file_path).expect("Should have been able to read the file");println!("With text:\n{contents}");}

示例 12-4：读取第二个参数所指定的文件内容

首先，我们增加了一个 use 语句来引入标准库中的相关部分：我们需要 std::fs 来处理文件。

在 main 中新增了一行语句：fs::read_to_string 接受 file_path，打开文件，接着返回包含其内容的 std::io::Result。

在这些代码之后，我们再次增加了临时的 println! 打印出读取文件之后 contents 的值，这样就可以检查目前为止的程序能否工作。

尝试运行这些代码，随意指定一个字符串作为第一个命令行参数（因为还未实现搜索功能的部分）而将 poem.txt 文件将作为第二个参数：

$ cargo run -- the poem.txt Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 0.0s Running `target/debug/minigrep the poem.txt`Searching for theIn file poem.txtWith text:I'm nobody! Who are you?Are you nobody, too?Then there's a pair of us - don't tell!They'd banish us, you know.How dreary to be somebody!How public, like a frogTo tell your name the livelong dayTo an admiring bog!

好的！代码读取并打印出了文件的内容。虽然它还有一些瑕疵：此时 main 函数有着多个职能，通常函数只负责一个功能的话会更简洁并易于维护。另一个问题是没有尽可能的处理错误。虽然我们的程序还很小，这些瑕疵并不是什么大问题，不过随着程序功能的丰富，将会越来越难以用简单的方法修复他们。在开发程序时，及早开始重构是一个最佳实践，因为重构少量代码时要容易的多，所以让我们现在就开始吧。

12.3重构改进模块性和错误处理

为了改善我们的程序这里有四个问题需要修复，而且他们都与程序的组织方式和如何处理潜在错误有关。第一，main 现在进行了两个任务：它解析了参数并打开了文件。对于一个这样的小函数，这并不是一个大问题。然而如果 main 中的功能持续增加，main 函数处理的独立任务也会增加。当函数承担了更多责任，它就更难以推导，更难以测试，并且更难以在不破坏其他部分的情况下做出修改。最好能分离出功能以便每个函数就负责一个任务。

这同时也关系到第二个问题：query 和 file_path 是程序中的配置变量，而像 contents 则用来执行程序逻辑。随着 main 函数的增长，就需要引入更多的变量到作用域中，而当作用域中有更多的变量时，将更难以追踪每个变量的目的。最好能将配置变量组织进一个结构，这样就能使他们的目的更明确了。

第三个问题是如果打开文件失败我们使用 expect 来打印出错误信息，不过这个错误信息只是说 Should have been able to read the file。读取文件失败的原因有多种：例如文件不存在，或者没有打开此文件的权限。目前，无论处于何种情况，我们只是打印出“文件读取出现错误”的信息，这并没有给予使用者具体的信息！

第四，我们不停地使用 expect 来处理不同的错误，如果用户没有指定足够的参数来运行程序，他们会从 Rust 得到 index out of bounds 错误，而这并不能明确地解释问题。如果所有的错误处理都位于一处，这样将来的维护者在需要修改错误处理逻辑时就只需要考虑这一处代码。将所有的错误处理都放在一处也有助于确保我们打印的错误信息对终端用户来说是有意义的。

让我们通过重构项目来解决这些问题。

二进制项目的关注分离

main 函数负责多个任务的组织问题在许多二进制项目中很常见。所以 Rust 社区开发出一类在 main 函数开始变得庞大时进行二进制程序的关注分离的指导。这些过程有如下步骤：

  • 将程序拆分成 main.rs 和 lib.rs 并将程序的逻辑放入 lib.rs 中。
  • 当命令行解析逻辑比较小时，可以保留在 main.rs 中。
  • 当命令行解析开始变得复杂时，也同样将其从 main.rs 提取到 lib.rs 中。

经过这些过程之后保留在 main 函数中的责任应该被限制为：

  • 使用参数值调用命令行解析逻辑
  • 设置任何其他的配置
  • 调用 lib.rs 中的 run 函数
  • 如果 run 返回错误，则处理这个错误

这个模式的一切就是为了关注分离：main.rs 处理程序运行，而 lib.rs 处理所有的真正的任务逻辑。因为不能直接测试 main 函数，这个结构通过将所有的程序逻辑移动到 lib.rs 的函数中使得我们可以测试他们。仅仅保留在 main.rs 中的代码将足够小以便阅读就可以验证其正确性。让我们遵循这些步骤来重构程序。

提取参数解析器

首先，我们将解析参数的功能提取到一个 main 将会调用的函数中，为将命令行解析逻辑移动到 src/lib.rs 中做准备。示例 12-5 中展示了新 main 函数的开头，它调用了新函数 parse_config。目前它仍将定义在 src/main.rs 中：

文件名：src/main.rs

fn main() {let args: Vec<String> = env::args().collect();let (query, file_path) = parse_config(&args);// --snip--}fn parse_config(args: &[String]) -> (&str, &str) {let query = &args[1];let file_path = &args[2];(query, file_path)}

示例 12-5：从 main 中提取出 parse_config 函数

我们仍然将命令行参数收集进一个 vector，不过不同于在 main 函数中将索引 1 的参数值赋值给变量 query 和将索引 2 的值赋值给变量 file_path，我们将整个 vector 传递给 parse_config 函数。接着 parse_config 函数将包含决定哪个参数该放入哪个变量的逻辑，并将这些值返回到 main。仍然在 main 中创建变量 query 和 file_path，不过 main 不再负责处理命令行参数与变量如何对应。

这对重构我们这小程序可能有点大材小用，不过我们将采用小的、增量的步骤进行重构。在做出这些改变之后，再次运行程序并验证参数解析是否仍然正常。经常验证你的进展是一个好习惯，这样在遇到问题时能帮助你定位问题的成因。

组合配置值

我们可以采取另一个小的步骤来进一步改善这个函数。现在函数返回一个元组，不过立刻又将元组拆成了独立的部分。这是一个我们可能没有进行正确抽象的信号。

另一个表明还有改进空间的迹象是 parse_config 名称的 config 部分，它暗示了我们返回的两个值是相关的并都是一个配置值的一部分。目前除了将这两个值组合进元组之外并没有表达这个数据结构的意义：我们可以将这两个值放入一个结构体并给每个字段一个有意义的名字。这会让未来的维护者更容易理解不同的值如何相互关联以及他们的目的。

注意：一些同学将这种在复杂类型更为合适的场景下使用基本类型的反模式称为 基本类型偏执（primitive obsession）。

示例 12-6 展示了 parse_config 函数的改进。

文件名：src/main.rs

fn main() {let args: Vec<String> = env::args().collect();let config = parse_config(&args);println!("Searching for {}", config.query);println!("In file {}", config.file_path);let contents = fs::read_to_string(config.file_path).expect("Should have been able to read the file");// --snip--}struct Config {query: String,file_path: String,}fn parse_config(args: &[String]) -> Config {let query = args[1].clone();let file_path = args[2].clone();Config { query, file_path }}

示例 12-6：重构 parse_config 返回一个 Config 结构体实例

新定义的结构体 Config 中包含字段 query 和 file_path。 parse_config 的签名表明它现在返回一个 Config 值。在之前的 parse_config 函数体中，我们返回了引用 args 中 String 值的字符串 slice，现在我们定义 Config 来包含拥有所有权的 String 值。main 中的 args 变量是参数值的所有者并只允许 parse_config 函数借用他们，这意味着如果 Config 尝试获取 args 中值的所有权将违反 Rust 的借用规则。

还有许多不同的方式可以处理 String 的数据，而最简单但有些不太高效的方式是调用这些值的 clone 方法。这会生成 Config 实例可以拥有的数据的完整拷贝，不过会比储存字符串数据的引用消耗更多的时间和内存。不过拷贝数据使得代码显得更加直白因为无需管理引用的生命周期，所以在这种情况下牺牲一小部分性能来换取简洁性的取舍是值得的。

使用 clone 的权衡取舍

由于其运行时消耗，许多 Rustacean 之间有一个趋势是倾向于避免使用 clone 来解决所有权问题。在关于迭代器的第十三章中，我们将会学习如何更有效率的处理这种情况，不过现在，复制一些字符串来取得进展是没有问题的，因为只会进行一次这样的拷贝，而且文件路径和要搜索的字符串都比较短。在第一轮编写时拥有一个可以工作但有点低效的程序要比尝试过度优化代码更好一些。随着你对 Rust 更加熟练，将能更轻松的直奔合适的方法，不过现在调用 clone 是完全可以接受的。

我们更新 main 将 parse_config 返回的 Config 实例放入变量 config 中，并将之前分别使用 query 和 file_path 变量的代码更新为现在的使用 Config 结构体的字段的代码。

现在代码更明确的表现了我们的意图，query 和 file_path 是相关联的并且他们的目的是配置程序如何工作。任何使用这些值的代码就知道在 config 实例中对应目的的字段名中寻找他们。

创建一个 Config 的构造函数

目前为止，我们将负责解析命令行参数的逻辑从 main 提取到了 parse_config 函数中，这有助于我们看清值 query 和 file_path 是相互关联的并应该在代码中表现这种关系。接着我们增加了 Config 结构体来描述 query 和 file_path 的相关性，并能够从 parse_config 函数中将这些值的名称作为结构体字段名称返回。

所以现在 parse_config 函数的目的是创建一个 Config 实例，我们可以将 parse_config 从一个普通函数变为一个叫做 new 的与结构体关联的函数。做出这个改变使得代码更符合习惯：可以像标准库中的 String 调用 String::new 来创建一个该类型的实例那样，将 parse_config 变为一个与 Config 关联的 new 函数。示例 12-7 展示了需要做出的修改：

文件名：src/main.rs

fn main() {let args: Vec<String> = env::args().collect();let config = Config::new(&args);// --snip--}// --snip--impl Config {fn new(args: &[String]) -> Config {let query = args[1].clone();let file_path = args[2].clone();Config { query, file_path }}}

示例 12-7：将 parse_config 变为 Config::new

这里将 main 中调用 parse_config 的地方更新为调用 Config::new。我们将 parse_config 的名字改为 new 并将其移动到 impl 块中，这使得 new 函数与 Config 相关联。再次尝试编译并确保它可以工作。

修复错误处理

现在我们开始修复错误处理。回忆一下之前提到过如果 args vector 包含少于 3 个项并尝试访问 vector 中索引 1 或索引 2 的值会造成程序 panic。尝试不带任何参数运行程序；这将看起来像这样：

$ cargo run Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 0.0s Running `target/debug/minigrep`thread 'main' panicked at 'index out of bounds: the len is 1 but the index is 1', src/main.rs:27:21note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

index out of bounds: the len is 1 but the index is 1 是一个针对程序员的错误信息，然而这并不能真正帮助终端用户理解发生了什么和他们应该做什么。现在就让我们修复它吧。

改善错误信息

在示例 12-8 中，在 new 函数中增加了一个检查在访问索引 1 和 2 之前检查 slice 是否足够长。如果 slice 不够长，程序会打印一个更好的错误信息并 panic：

文件名：src/main.rs

// --snip--fn new(args: &[String]) -> Config {if args.len() < 3 {panic!("not enough arguments");}// --snip--

示例 12-8：增加一个参数数量检查

这类似于 示例 9-13 中的 Guess::new 函数，那里如果 value 参数超出了有效值的范围就调用 panic!。不同于检查值的范围，这里检查 args 的长度至少是 3，而函数的剩余部分则可以在假设这个条件成立的基础上运行。如果 args 少于 3 个项，则这个条件将为真，并调用 panic! 立即终止程序。

有了 new 中这几行额外的代码，再次不带任何参数运行程序并看看现在错误看起来像什么：

$ cargo run Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 0.0s Running `target/debug/minigrep`thread 'main' panicked at 'not enough arguments', src/main.rs:26:13note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

这个输出就好多了，现在有了一个合理的错误信息。然而，还是有一堆额外的信息我们不希望提供给用户。所以在这里使用示例 9-9 中的技术可能不是最好的；正如 第九章 所讲到的一样，panic! 的调用更趋向于程序上的问题而不是使用上的问题。相反我们可以使用第九章学习的另一个技术 —— 返回一个可以表明成功或错误的 Result。

从 new 中返回 Result 而不是调用 panic!

我们可以选择返回一个 Result 值，它在成功时会包含一个 Config 的实例，而在错误时会描述问题。我们还将把函数名从new改为build，因为许多程序员希望 new 函数永远不会失败。当 Config::new 与 main 交流时，可以使用 Result 类型来表明这里存在问题。接着修改 main 将 Err 成员转换为对用户更友好的错误，而不是 panic! 调用产生的关于 thread 'main' 和 RUST_BACKTRACE 的文本。

示例 12-9 展示了为了返回 Result 在 Config::new 的返回值和函数体中所需的改变。注意这还不能编译，直到下一个示例同时也更新了 main 之后。

文件名：src/main.rs

impl Config {fn build(args: &[String]) -> Result<Config, &'static str> {if args.len() < 3 {return Err("not enough arguments");}let query = args[1].clone();let file_path = args[2].clone();Ok(Config { query, file_path })}}

示例 12-9：从 Config::build 中返回 Result

现在 build 函数返回一个 Result，在成功时带有一个 Config 实例而在出现错误时带有一个 &'static str。回忆一下第十章 “静态生命周期” 中讲到 &'static str 是字符串字面值的类型，也是目前的错误信息。

new 函数体中有两处修改：当没有足够参数时不再调用 panic!，而是返回 Err 值。同时我们将 Config 返回值包装进 Ok 成员中。这些修改使得函数符合其新的类型签名。

通过让 Config::build 返回一个 Err 值，这就允许 main 函数处理 new 函数返回的 Result 值并在出现错误的情况更明确的结束进程。

Config::build 调用并处理错误

为了处理错误情况并打印一个对用户友好的信息，我们需要像示例 12-10 那样更新 main 函数来处理现在 Config::build 返回的 Result。另外还需要手动实现原先由 panic!负责的工作，即以非零错误码退出命令行工具的工作。非零的退出状态是一个惯例信号，用来告诉调用程序的进程：该程序以错误状态退出了。

文件名：src/main.rs

use std::process;fn main() {let args: Vec<String> = env::args().collect();let config = Config::build(&args).unwrap_or_else(|err| {println!("Problem parsing arguments: {err}");process::exit(1);});// --snip--

示例 12-10：如果新建 Config 失败则使用错误码退出

在上面的示例中，使用了一个之前没有详细说明的方法：unwrap_or_else，它定义于标准库的 Result 上。使用 unwrap_or_else 可以进行一些自定义的非 panic! 的错误处理。当 Result 是 Ok 时，这个方法的行为类似于 unwrap：它返回 Ok 内部封装的值。然而，当其值是 Err 时，该方法会调用一个 闭包（closure），也就是一个我们定义的作为参数传递给 unwrap_or_else 的匿名函数。第十三章 会更详细的介绍闭包。现在你需要理解的是 unwrap_or_else 会将 Err 的内部值，也就是示例 12-9 中增加的 not enough arguments 静态字符串的情况，传递给闭包中位于两道竖线间的参数 err。闭包中的代码在其运行时可以使用这个 err 值。

我们新增了一个 use 行来从标准库中导入 process。在错误的情况闭包中将被运行的代码只有两行：我们打印出了 err 值，接着调用了 std::process::exit。process::exit 会立即停止程序并将传递给它的数字作为退出状态码。这类似于示例 12-8 中使用的基于 panic! 的错误处理，除了不会再得到所有的额外输出了。让我们试试：

$ cargo run Compiling minigrep v0.1.0 (file:///projects/minigrep)Finished dev [unoptimized + debuginfo] target(s) in 0.48s Running `target/debug/minigrep`Problem parsing arguments: not enough arguments

非常好！现在输出对于用户来说就友好多了。

从 main 提取逻辑

现在我们完成了配置解析的重构：让我们转向程序的逻辑。正如 “二进制项目的关注分离” 部分所展开的讨论，我们将提取一个叫做 run 的函数来存放目前 main 函数中不属于设置配置或处理错误的所有逻辑。一旦完成这些，main 函数将简明得足以通过观察来验证，而我们将能够为所有其他逻辑编写测试。

示例 12-11 展示了提取出来的 run 函数。目前我们只进行小的增量式的提取函数的改进。我们仍将在 src/main.rs 中定义这个函数：

文件名：src/main.rs

fn main() {// --snip--println!("Searching for {}", config.query);println!("In file {}", config.file_path);run(config);}fn run(config: Config) {let contents = fs::read_to_string(config.file_path).expect("Should have been able to read the file");println!("With text:\n{contents}");}// --snip--

示例 12-11：提取 run 函数来包含剩余的程序逻辑

现在 run 函数包含了 main 中从读取文件开始的剩余的所有逻辑。run 函数获取一个 Config 实例作为参数。

从 run 函数中返回错误

通过将剩余的逻辑分离进 run 函数而不是留在 main 中，就可以像示例 12-9 中的 Config::build 那样改进错误处理。不再通过 expect 允许程序 panic，run 函数将会在出错时返回一个 Result。这让我们进一步以一种对用户友好的方式统一 main 中的错误处理。示例 12-12 展示了 run 签名和函数体中的改变：

文件名：src/main.rs

use std::error::Error;// --snip--fn run(config: Config) -> Result<(), Box<dyn Error>> {let contents = fs::read_to_string(config.file_path)?;println!("With text:\n{contents}");Ok(())}

示例 12-12：修改 run 函数返回 Result

这里我们做出了三个明显的修改。首先，将 run 函数的返回类型变为 Result<(), Box>。之前这个函数返回 unit 类型 ()，现在它仍然保持作为 Ok 时的返回值。

对于错误类型，使用了 trait 对象 Box（在开头使用了 use 语句将 std::error::Error 引入作用域）。第十七章 会涉及 trait 对象。目前只需知道 Box 意味着函数会返回实现了 Error trait 的类型，不过无需指定具体将会返回的值的类型。这提供了在不同的错误场景可能有不同类型的错误返回值的灵活性。这也就是 dyn，它是 “动态的”（“dynamic”）的缩写。

第二个改变是去掉了 expect 调用并替换为 第九章 讲到的 ?。不同于遇到错误就 panic!，? 会从函数中返回错误值并让调用者来处理它。

第三个修改是现在成功时这个函数会返回一个 Ok 值。因为 run 函数签名中声明成功类型返回值是 ()，这意味着需要将 unit 类型值包装进 Ok 值中。Ok(()) 一开始看起来有点奇怪，不过这样使用 () 是惯用的做法，表明调用 run 函数只是为了它的副作用；函数并没有返回什么有意义的值。

上述代码能够编译，不过会有一个警告：

$ cargo run the poem.txt Compiling minigrep v0.1.0 (file:///projects/minigrep)warning: unused `Result` that must be used--> src/main.rs:19:5 |19 | run(config); | ^^^^^^^^^^^^ | = note: `#[warn(unused_must_use)]` on by default = note: this `Result` may be an `Err` variant, which should be handledwarning: `minigrep` (bin "minigrep") generated 1 warningFinished dev [unoptimized + debuginfo] target(s) in 0.71s Running `target/debug/minigrep the poem.txt`Searching for theIn file poem.txtWith text:I'm nobody! Who are you?Are you nobody, too?Then there's a pair of us - don't tell!They'd banish us, you know.How dreary to be somebody!How public, like a frogTo tell your name the livelong dayTo an admiring bog!

Rust 提示我们的代码忽略了 Result 值，它可能表明这里存在一个错误。但我们却没有检查这里是否有一个错误，而编译器提醒我们这里应该有一些错误处理代码！现在就让我们修正这个问题。

处理 main 中 run 返回的错误

我们将检查错误并使用类似示例 12-10 中 Config::build 处理错误的技术来处理他们，不过有一些细微的不同：

文件名：src/main.rs

fn main() {// --snip--println!("Searching for {}", config.query);println!("In file {}", config.file_path);if let Err(e) = run(config) {println!("Application error: {e}");process::exit(1);}}

我们使用 if let 来检查 run 是否返回一个 Err 值，不同于 unwrap_or_else，并在出错时调用 process::exit(1)。run 并不返回像 Config::build 返回的 Config 实例那样需要 unwrap 的值。因为 run 在成功时返回 ()，而我们只关心检测错误，所以并不需要 unwrap_or_else 来返回未封装的值，因为它只会是 ()。

不过两个例子中 if let 和 unwrap_or_else 的函数体都一样：打印出错误并退出。

将代码拆分到库 crate

现在我们的 minigrep 项目看起来好多了！现在我们将要拆分 src/main.rs 并将一些代码放入 src/lib.rs，这样就能测试他们并拥有一个含有更少功能的 main 函数。

让我们将所有不是 main 函数的代码从 src/main.rs 移动到新文件 src/lib.rs 中：

  • run 函数定义
  • 相关的 use 语句
  • Config 的定义
  • Config::build 函数定义

现在 src/lib.rs 的内容应该看起来像示例 12-13（为了简洁省略了函数体）。注意直到下一个示例修改完 src/main.rs 之后，代码还不能编译：

文件名：src/lib.rs

use std::error::Error;use std::fs;pub struct Config {pub query: String,pub file_path: String,}impl Config {pub fn build(args: &[String]) -> Result<Config, &'static str> {// --snip--}}pub fn run(config: Config) -> Result<(), Box<dyn Error>> {// --snip--}

示例 12-13：将 Config 和 run 移动到 src/lib.rs

这里使用了公有的 pub 关键字：在 Config、其字段和其 build 方法，以及 run 函数上。现在我们有了一个拥有可以测试的公有 API 的库 crate 了。

现在需要在 src/main.rs 中将移动到 src/lib.rs 的代码引入二进制 crate 的作用域中，如示例 12-14 所示：

文件名：src/main.rs

use std::env;use std::process;use minigrep::Config;fn main() {// --snip--if let Err(e) = minigrep::run(config) {// --snip--}}

示例 12-14：将 minigrep crate 引入 src/main.rs 的作用域中

我们添加了一行 use minigrep::Config，它将 Config 类型引入作用域，并使用 crate 名称作为 run 函数的前缀。通过这些重构，所有功能应该能够联系在一起并运行了。运行 cargo run 来确保一切都正确的衔接在一起。

哇哦！我们做了大量的工作，不过我们为将来的成功打下了基础。现在处理错误将更容易，同时代码也更加模块化。从现在开始几乎所有的工作都将在 src/lib.rs 中进行。

让我们利用这些新创建的模块的优势来进行一些在旧代码中难以展开的工作，这些工作在新代码中非常容易实现，那就是：编写测试！

示例 12-14：将 `minigrep` crate 引入 *src/main.rs* 的作用域中我们添加了一行 `use minigrep::Config`，它将 `Config` 类型引入作用域，并使用 crate 名称作为 `run` 函数的前缀。通过这些重构，所有功能应该能够联系在一起并运行了。运行 `cargo run` 来确保一切都正确的衔接在一起。哇哦！我们做了大量的工作，不过我们为将来的成功打下了基础。现在处理错误将更容易，同时代码也更加模块化。从现在开始几乎所有的工作都将在 *src/lib.rs* 中进行。让我们利用这些新创建的模块的优势来进行一些在旧代码中难以展开的工作，这些工作在新代码中非常容易实现，那就是：编写测试！