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
usestd::env;fnmain(){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
usestd::env;fnmain(){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 test
In 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 frog
To tell your name the livelong day
To an admiring bog!
示例 12-3：艾米莉·狄金森的诗 “I’m nobody! Who are you?”，一个好的测试用例
创建完这个文件之后，修改 src/main.rs 并增加如示例 12-4 所示的打开文件的代码：
文件名：src/main.rs
usestd::env;usestd::fs;fnmain(){// --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<String>
。
在这些代码之后，我们再次增加了临时的
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 the
In file poem.txt
With 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 frog
To tell your name the livelong day
To 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
fnmain(){let args:Vec<String>=env::args().collect();let(query, file_path)=parse_config(&args);// --snip--}fnparse_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
fnmain(){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--}structConfig{
query:String,
file_path:String,}fnparse_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
fnmain(){let args:Vec<String>=env::args().collect();let config =Config::new(&args);// --snip--}// --snip--implConfig{fnnew(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:21
note: 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--fnnew(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:13
note: 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
implConfig{fnbuild(args:&[String])->Result<Config,&'staticstr>{if args.len()<3{returnErr("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
usestd::process;fnmain(){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<T, E>
上。使用
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
fnmain(){// --snip--println!("Searching for {}", config.query);println!("In file {}", config.file_path);run(config);}fnrun(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<T, E>
。这让我们进一步以一种对用户友好的方式统一
main
中的错误处理。示例 12-12 展示了
run
签名和函数体中的改变：
文件名：src/main.rs
usestd::error::Error;// --snip--fnrun(config:Config)->Result<(),Box<dynError>>{let contents =fs::read_to_string(config.file_path)?;println!("With text:\n{contents}");Ok(())}
示例 12-12：修改
run
函数返回
Result
这里我们做出了三个明显的修改。首先，将
run
函数的返回类型变为
Result<(), Box<dyn Error>>
。之前这个函数返回 unit 类型
()
，现在它仍然保持作为
Ok
时的返回值。
对于错误类型，使用了 trait 对象
Box<dyn Error>
（在开头使用了
use
语句将
std::error::Error
引入作用域）。第十七章 会涉及 trait 对象。目前只需知道
Box<dyn Error>
意味着函数会返回实现了
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 handled
warning: `minigrep` (bin "minigrep") generated 1 warning
Finished dev [unoptimized + debuginfo] target(s) in 0.71s
Running `target/debug/minigrep the poem.txt`
Searching for the
In file poem.txt
With 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 frog
To tell your name the livelong day
To an admiring bog!
Rust 提示我们的代码忽略了
Result
值，它可能表明这里存在一个错误。但我们却没有检查这里是否有一个错误，而编译器提醒我们这里应该有一些错误处理代码！现在就让我们修正这个问题。
处理
main
中
run
返回的错误
我们将检查错误并使用类似示例 12-10 中
Config::build
处理错误的技术来处理他们，不过有一些细微的不同：
文件名：src/main.rs
fnmain(){// --snip--println!("Searching for {}", config.query);println!("In file {}", config.file_path);ifletErr(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
usestd::error::Error;usestd::fs;pubstructConfig{pub query:String,pub file_path:String,}implConfig{pubfnbuild(args:&[String])->Result<Config,&'staticstr>{// --snip--}}pubfnrun(config:Config)->Result<(),Box<dynError>>{// --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
usestd::env;usestd::process;useminigrep::Config;fnmain(){// --snip--ifletErr(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 社区的成员，AndrewGallant，已经创建了一个功能完整且非常快速的 `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
Createdbinary(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
usestd::env;fnmain(){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
usestd::env;fnmain(){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 test
In 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 frog
To tell your name the livelong day
To an admiring bog!
示例 12-3：艾米莉·狄金森的诗 “I’m nobody! Who are you?”，一个好的测试用例
创建完这个文件之后，修改 src/main.rs 并增加如示例 12-4 所示的打开文件的代码：
文件名：src/main.rs
usestd::env;usestd::fs;fnmain(){// --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<String>
。
在这些代码之后，我们再次增加了临时的
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 the
In file poem.txt
With 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 frog
To tell your name the livelong day
To 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
fnmain(){let args:Vec<String>=env::args().collect();let(query, file_path)=parse_config(&args);// --snip--}fnparse_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
fnmain(){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--}structConfig{
query:String,
file_path:String,}fnparse_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
fnmain(){let args:Vec<String>=env::args().collect();let config =Config::new(&args);// --snip--}// --snip--implConfig{fnnew(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:21
note: 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--fnnew(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:13
note: 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
implConfig{fnbuild(args:&[String])->Result<Config,&'staticstr>{if args.len()<3{returnErr("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
usestd::process;fnmain(){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<T, E>
上。使用
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
fnmain(){// --snip--println!("Searching for {}", config.query);println!("In file {}", config.file_path);run(config);}fnrun(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<T, E>
。这让我们进一步以一种对用户友好的方式统一
main
中的错误处理。示例 12-12 展示了
run
签名和函数体中的改变：
文件名：src/main.rs
usestd::error::Error;// --snip--fnrun(config:Config)->Result<(),Box<dynError>>{let contents =fs::read_to_string(config.file_path)?;println!("With text:\n{contents}");Ok(())}
示例 12-12：修改
run
函数返回
Result
这里我们做出了三个明显的修改。首先，将
run
函数的返回类型变为
Result<(), Box<dyn Error>>
。之前这个函数返回 unit 类型
()
，现在它仍然保持作为
Ok
时的返回值。
对于错误类型，使用了 trait 对象
Box<dyn Error>
（在开头使用了
use
语句将
std::error::Error
引入作用域）。第十七章 会涉及 trait 对象。目前只需知道
Box<dyn Error>
意味着函数会返回实现了
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 handled
warning: `minigrep` (bin "minigrep") generated 1 warning
Finished dev [unoptimized + debuginfo] target(s) in 0.71s
Running `target/debug/minigrep the poem.txt`
Searching for the
In file poem.txt
With 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 frog
To tell your name the livelong day
To an admiring bog!
Rust 提示我们的代码忽略了
Result
值，它可能表明这里存在一个错误。但我们却没有检查这里是否有一个错误，而编译器提醒我们这里应该有一些错误处理代码！现在就让我们修正这个问题。
处理
main
中
run
返回的错误
我们将检查错误并使用类似示例 12-10 中
Config::build
处理错误的技术来处理他们，不过有一些细微的不同：
文件名：src/main.rs
fnmain(){// --snip--println!("Searching for {}", config.query);println!("In file {}", config.file_path);ifletErr(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
usestd::error::Error;usestd::fs;pubstructConfig{pub query:String,pub file_path:String,}implConfig{pubfnbuild(args:&[String])->Result<Config,&'staticstr>{// --snip--}}pubfnrun(config:Config)->Result<(),Box<dynError>>{// --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
usestd::env;usestd::process;useminigrep::Config;fnmain(){// --snip--ifletErr(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* 中进行。
让我们利用这些新创建的模块的优势来进行一些在旧代码中难以展开的工作，这些工作在新代码中非常容易实现，那就是：编写测试！
版权归原作者 谦谦孑 所有， 如有侵权，请联系我们删除。