要不要 panic!
To panic! or Not to panic!
那么，你该如何决定何时应该调用 panic!，何时应该返回 Result 呢？当代码发生 panic 时，没有办法恢复。你可以针对任何错误情况调用 panic!，无论是否有恢复的可能，但这样你就是在代表调用代码做出“某种情况不可恢复”的决定。当你选择返回 Result 值时，你给了调用代码更多的选择。调用代码可以选择以适合其情况的方式尝试恢复，或者它可以决定在这种情况下 Err 值是不可恢复的，因此它可以调用 panic! 并将你的可恢复错误转变为不可恢复错误。因此，当你定义一个可能失败的函数时，返回 Result 是一个很好的默认选择。
So, how do you decide when you should call panic! and when you should return Result? When code panics, there’s no way to recover. You could call panic! for any error situation, whether there’s a possible way to recover or not, but then you’re making the decision that a situation is unrecoverable on behalf of the calling code. When you choose to return a Result value, you give the calling code options. The calling code could choose to attempt to recover in a way that’s appropriate for its situation, or it could decide that an Err value in this case is unrecoverable, so it can call panic! and turn your recoverable error into an unrecoverable one. Therefore, returning Result is a good default choice when you’re defining a function that might fail.
在示例、原型代码和测试等情况下，编写会发生 panic 的代码比返回 Result 更合适。让我们探讨一下原因，然后讨论一些编译器无法判断失败是否是不可能的，但你作为人类却可以判断的情况。本章最后将提供一些关于如何决定在库代码中是否使用 panic 的通用指南。
In situations such as examples, prototype code, and tests, it’s more appropriate to write code that panics instead of returning a Result. Let’s explore why, then discuss situations in which the compiler can’t tell that failure is impossible, but you as a human can. The chapter will conclude with some general guidelines on how to decide whether to panic in library code.
示例、原型代码和测试
Examples, Prototype Code, and Tests
当你编写示例来阐明某些概念时，如果还包含健壮的错误处理代码，可能会使示例变得不那么清晰。在示例中，人们理解像 unwrap 这样可能导致 panic 的方法调用只是你希望应用程序处理错误方式的一个占位符，而具体的处理方式可以根据你代码的其他部分在做什么而有所不同。
When you’re writing an example to illustrate some concept, also including robust error-handling code can make the example less clear. In examples, it’s understood that a call to a method like unwrap that could panic is meant as a placeholder for the way you’d want your application to handle errors, which can differ based on what the rest of your code is doing.
同样，当你正在编写原型且尚未决定如何处理错误时，unwrap 和 expect 方法非常方便。它们在你的代码中留下了清晰的标记，以便当你准备好让程序更健壮时进行修改。
Similarly, the unwrap and expect methods are very handy when you’re prototyping and you’re not yet ready to decide how to handle errors. They leave clear markers in your code for when you’re ready to make your program more robust.
如果测试中的某个方法调用失败，你肯定希望整个测试都失败，即使该方法不是被测试的功能。因为 panic! 是标记测试失败的方式，所以调用 unwrap 或 expect 正是应该发生的。
If a method call fails in a test, you’d want the whole test to fail, even if that method isn’t the functionality under test. Because panic! is how a test is marked as a failure, calling unwrap or expect is exactly what should happen.
当你拥有比编译器更多的信息时
When You Have More Information Than the Compiler
当你拥有其他逻辑可以确保 Result 必定拥有 Ok 值，但该逻辑是编译器无法理解的东西时，调用 expect 也是合适的。你仍然有一个需要处理的 Result 值：你调用的任何操作通常仍然有失败的可能性，尽管在你特定的情况下在逻辑上是不可能的。如果你可以通过手动检查代码来确保永远不会出现 Err 变体，那么调用 expect 并在参数文本中记录你认为永远不会出现 Err 变体的原因是完全可以接受的。这里有一个例子：
It would also be appropriate to call expect when you have some other logic that ensures that the Result will have an Ok value, but the logic isn’t something the compiler understands. You’ll still have a Result value that you need to handle: Whatever operation you’re calling still has the possibility of failing in general, even though it’s logically impossible in your particular situation. If you can ensure by manually inspecting the code that you’ll never have an Err variant, it’s perfectly acceptable to call expect and document the reason you think you’ll never have an Err variant in the argument text. Here’s an example:
fn main() {
use std::net::IpAddr;
let home: IpAddr = "127.0.0.1"
.parse()
.expect("Hardcoded IP address should be valid");
}我们正在通过解析硬编码的字符串来创建一个 IpAddr 实例。我们可以看到 127.0.0.1 是一个有效的 IP 地址，因此在这里使用 expect 是可以接受的。然而，拥有一个硬编码的、有效的字符串并不会改变 parse 方法的返回类型：我们仍然会得到一个 Result 值，并且编译器仍然会要求我们像处理 Err 变体可能出现的情况一样处理这个 Result，因为编译器不够聪明，看不出这个字符串始终是一个有效的 IP 地址。如果 IP 地址字符串来自用户而不是硬编码在程序中，因此确实有失败的可能性，我们肯定会希望以一种更健壮的方式来处理 Result。提及“此 IP 地址是硬编码的”这一假设，会提示我们在将来如果需要从其他来源获取 IP 地址时，将 expect 更改为更好的错误处理代码。
We’re creating an IpAddr instance by parsing a hardcoded string. We can see that 127.0.0.1 is a valid IP address, so it’s acceptable to use expect here. However, having a hardcoded, valid string doesn’t change the return type of the parse method: We still get a Result value, and the compiler will still make us handle the Result as if the Err variant is a possibility because the compiler isn’t smart enough to see that this string is always a valid IP address. If the IP address string came from a user rather than being hardcoded into the program and therefore did have a possibility of failure, we’d definitely want to handle the Result in a more robust way instead. Mentioning the assumption that this IP address is hardcoded will prompt us to change expect to better error-handling code if, in the future, we need to get the IP address from some other source instead.
错误处理指南
Guidelines for Error Handling
当你的代码可能陷入糟糕的状态时，建议让你的代码发生 panic。在这种情况下，糟糕的状态 是指某些假设、保证、契约或不变性被打破，例如将无效值、矛盾值或缺失值传递给你的代码——并且满足以下一个或多个条件：
It’s advisable to have your code panic when it’s possible that your code could end up in a bad state. In this context, a bad state is when some assumption, guarantee, contract, or invariant has been broken, such as when invalid values, contradictory values, or missing values are passed to your code—plus one or more of the following:
-
糟糕的状态是意料之外的事情，而不是像用户以错误的格式输入数据那样可能偶尔发生的事情。
-
The bad state is something that is unexpected, as opposed to something that will likely happen occasionally, like a user entering data in the wrong format.
-
在此之后的代码需要依赖于不处于这种糟糕的状态，而不是在每一步都检查该问题。
-
Your code after this point needs to rely on not being in this bad state, rather than checking for the problem at every step.
-
没有一种很好的方法可以将此信息编码到你使用的类型中。我们将在第 18 章的“将状态和行为编码为类型”中详细介绍我们的意思。
-
There’s not a good way to encode this information in the types you use. We’ll work through an example of what we mean in “Encoding States and Behavior as Types” in Chapter 18.
如果有人调用你的代码并传入了没有意义的值，最好尽可能返回一个错误，以便库的用户可以决定在这种情况下他们想做什么。然而，在继续执行可能不安全或有害的情况下，最好的选择可能是调用 panic! 并提醒使用你的库的人他们的代码中有 Bug，以便他们可以在开发过程中修复它。同样地，如果你调用的外部代码不受你控制，并且它返回了一个你无法修复的无效状态，那么使用 panic! 通常也是合适的。
If someone calls your code and passes in values that don’t make sense, it’s best to return an error if you can so that the user of the library can decide what they want to do in that case. However, in cases where continuing could be insecure or harmful, the best choice might be to call panic! and alert the person using your library to the bug in their code so that they can fix it during development. Similarly, panic! is often appropriate if you’re calling external code that is out of your control and returns an invalid state that you have no way of fixing.
然而，当预期会发生失败时，返回 Result 比调用 panic! 更合适。例如，解析器被赋予了格式错误的数据，或者 HTTP 请求返回了一个表示你已达到速率限制的状态。在这些情况下，返回 Result 表示失败是一个预期的可能性，调用代码必须决定如何处理它。
However, when failure is expected, it’s more appropriate to return a Result than to make a panic! call. Examples include a parser being given malformed data or an HTTP request returning a status that indicates you have hit a rate limit. In these cases, returning a Result indicates that failure is an expected possibility that the calling code must decide how to handle.
当你的代码执行一项操作，如果使用无效值调用该操作可能会使用户面临风险时，你的代码应首先验证值是否有效，如果值无效则发生 panic。这主要是出于安全原因：尝试操作无效数据会使你的代码暴露在漏洞之下。这是如果你尝试进行越界内存访问时标准库会调用 panic! 的主要原因：尝试访问不属于当前数据结构的内存是一个常见的安全问题。函数通常有 契约（contract）：只有在输入满足特定要求时，其行为才能得到保证。在违反契约时发生 panic 是有道理的，因为违反契约始终表示调用方存在 Bug，这不是你希望调用代码必须显式处理的那种错误。事实上，调用代码没有合理的恢复方式；调用方的 程序员 需要修复代码。函数的契约，特别是当违约会导致 panic 时，应在函数的 API 文档中进行说明。
When your code performs an operation that could put a user at risk if it’s called using invalid values, your code should verify the values are valid first and panic if the values aren’t valid. This is mostly for safety reasons: Attempting to operate on invalid data can expose your code to vulnerabilities. This is the main reason the standard library will call panic! if you attempt an out-of-bounds memory access: Trying to access memory that doesn’t belong to the current data structure is a common security problem. Functions often have contracts: Their behavior is only guaranteed if the inputs meet particular requirements. Panicking when the contract is violated makes sense because a contract violation always indicates a caller-side bug, and it’s not a kind of error you want the calling code to have to explicitly handle. In fact, there’s no reasonable way for calling code to recover; the calling programmers need to fix the code. Contracts for a function, especially when a violation will cause a panic, should be explained in the API documentation for the function.
然而，在你所有的函数中都进行大量的错误检查会很冗长且令人烦恼。幸运的是，你可以使用 Rust 的类型系统（以及编译器完成的类型检查）来为你完成许多检查。如果你的函数有一个特定类型作为参数，你可以放心地继续执行你的代码逻辑，因为你知道编译器已经确保你拥有一个有效值。例如，如果你有一个具体的类型而不是 Option，你的程序预期会得到 某些东西 而不是 空。这样，你的代码就不必处理 Some 和 None 变体这两种情况：它只需处理确定有一个值的情况。尝试向你的函数传递空值的代码甚至无法编译，因此你的函数不必在运行时检查这种情况。另一个例子是使用无符号整数类型（如 u32），这可以确保参数永远不会是负数。
However, having lots of error checks in all of your functions would be verbose and annoying. Fortunately, you can use Rust’s type system (and thus the type checking done by the compiler) to do many of the checks for you. If your function has a particular type as a parameter, you can proceed with your code’s logic knowing that the compiler has already ensured that you have a valid value. For example, if you have a type rather than an Option, your program expects to have something rather than nothing. Your code then doesn’t have to handle two cases for the Some and None variants: It will only have one case for definitely having a value. Code trying to pass nothing to your function won’t even compile, so your function doesn’t have to check for that case at runtime. Another example is using an unsigned integer type such as u32, which ensures that the parameter is never negative.
用于验证的自定义类型
Custom Types for Validation
让我们更进一步，利用 Rust 的类型系统来确保我们拥有一个有效的值，并看看如何创建一个用于验证的自定义类型。回想一下第 2 章中的猜谜游戏，我们的代码要求用户猜一个 1 到 100 之间的数字。在将其与我们的秘密数字进行核对之前，我们从未验证过用户的猜测是否在这些数字之间；我们只验证了猜测是正数。在这种情况下，后果并不是很严重：我们输出的“太高了”或“太低了”仍然是正确的。但如果能引导用户进行有效的猜测，并且当用户猜了一个超出范围的数字时，与用户输入字母等情况相比有不同的行为，那将是一个非常有用的改进。
Let’s take the idea of using Rust’s type system to ensure that we have a valid value one step further and look at creating a custom type for validation. Recall the guessing game in Chapter 2 in which our code asked the user to guess a number between 1 and 100. We never validated that the user’s guess was between those numbers before checking it against our secret number; we only validated that the guess was positive. In this case, the consequences were not very dire: Our output of “Too high” or “Too low” would still be correct. But it would be a useful enhancement to guide the user toward valid guesses and have different behavior when the user guesses a number that’s out of range versus when the user types, for example, letters instead.
一种方法是将猜测解析为 i32 而不仅仅是 u32，以允许可能出现的负数，然后添加一个检查数字是否在范围内的判断，如下所示：
One way to do this would be to parse the guess as an i32 instead of only a u32 to allow potentially negative numbers, and then add a check for the number being in range, like so:
use rand::Rng;
use std::cmp::Ordering;
use std::io;
fn main() {
println!("Guess the number!");
let secret_number = rand::thread_rng().gen_range(1..=100);
loop {
// --snip--
println!("Please input your guess.");
let mut guess = String::new();
io::stdin()
.read_line(&mut guess)
.expect("Failed to read line");
let guess: i32 = match guess.trim().parse() {
Ok(num) => num,
Err(_) => continue,
};
if guess < 1 || guess > 100 {
println!("The secret number will be between 1 and 100.");
continue;
}
match guess.cmp(&secret_number) {
// --snip--
Ordering::Less => println!("Too small!"),
Ordering::Greater => println!("Too big!"),
Ordering::Equal => {
println!("You win!");
break;
}
}
}
}if 表达式检查我们的值是否超出范围，告诉用户相关问题，并调用 continue 开始循环的下一次迭代并请求另一个猜测。在 if 表达式之后，我们可以继续进行 guess 和秘密数字之间的比较，因为知道 guess 在 1 到 100 之间。
The if expression checks whether our value is out of range, tells the user about the problem, and calls continue to start the next iteration of the loop and ask for another guess. After the if expression, we can proceed with the comparisons between guess and the secret number knowing that guess is between 1 and 100.
然而，这并不是一个理想的解决方案：如果程序只在 1 到 100 之间的值上运行绝对至关重要，并且它有许多具有此要求的函数，那么在每个函数中都进行这样的检查将非常繁琐（并且可能会影响性能）。
However, this is not an ideal solution: If it were absolutely critical that the program only operated on values between 1 and 100, and it had many functions with this requirement, having a check like this in every function would be tedious (and might impact performance).
相反，我们可以在一个专用模块中创建一个新类型，并将验证逻辑放在创建该类型实例的函数中，而不是在到处重复验证。这样，函数在其签名中使用新类型并放心使用接收到的值就是安全的。示例 9-13 展示了定义 Guess 类型的一种方法，只有当 new 函数接收到 1 到 100 之间的值时，它才会创建 Guess 的实例。
Instead, we can make a new type in a dedicated module and put the validations in a function to create an instance of the type rather than repeating the validations everywhere. That way, it’s safe for functions to use the new type in their signatures and confidently use the values they receive. Listing 9-13 shows one way to define a Guess type that will only create an instance of Guess if the new function receives a value between 1 and 100.
#![allow(unused)]
fn main() {
pub struct Guess {
value: i32,
}
impl Guess {
pub fn new(value: i32) -> Guess {
if value < 1 || value > 100 {
panic!("Guess value must be between 1 and 100, got {value}.");
}
Guess { value }
}
pub fn value(&self) -> i32 {
self.value
}
}
}请注意，src/guessing_game.rs 中的这段代码依赖于我们在 src/lib.rs 中添加的模块声明 mod guessing_game;，这里我们没有展示。在这个新模块的文件中，我们定义了一个名为 Guess 的结构体，它有一个名为 value 的字段，用于保存 i32。这就是存储数字的地方。
Note that this code in src/guessing_game.rs depends on adding a module declaration mod guessing_game; in src/lib.rs that we haven’t shown here. Within this new module’s file, we define a struct named Guess that has a field named value that holds an i32. This is where the number will be stored.
然后，我们在 Guess 上实现了一个名为 new 的关联函数，用于创建 Guess 值的实例。new 函数定义为有一个名为 value 的 i32 类型参数，并返回一个 Guess。new 函数体内的代码测试 value 以确保其在 1 到 100 之间。如果 value 没有通过测试，我们会调用 panic!，这将提醒编写调用代码的程序员他们有一个需要修复的 Bug，因为使用超出此范围的 value 创建 Guess 会违反 Guess::new 所依赖的契约。Guess::new 可能发生 panic 的情况应在其面向公众的 API 文档中进行说明；我们将在第 14 章介绍 API 文档中指示可能发生 panic! 的编写惯例。如果 value 通过了测试，我们将创建一个新的 Guess，其 value 字段设置为 value 参数，并返回该 Guess。
Then, we implement an associated function named new on Guess that creates instances of Guess values. The new function is defined to have one parameter named value of type i32 and to return a Guess. The code in the body of the new function tests value to make sure it’s between 1 and 100. If value doesn’t pass this test, we make a panic! call, which will alert the programmer who is writing the calling code that they have a bug they need to fix, because creating a Guess with a value outside this range would violate the contract that Guess::new is relying on. The conditions in which Guess::new might panic should be discussed in its public-facing API documentation; we’ll cover documentation conventions indicating the possibility of a panic! in the API documentation that you create in Chapter 14. If value does pass the test, we create a new Guess with its value field set to the value parameter and return the Guess.
接下来，我们实现了一个名为 value 的方法，该方法借用 self，没有其他参数，并返回一个 i32。这类方法有时被称为 getter，因为其目的是从字段中获取某些数据并将其返回。这个公共方法是必要的，因为 Guess 结构体的 value 字段是私有的。value 字段必须是私有的，这一点很重要，这样使用 Guess 结构体的代码就不被允许直接设置 value：guessing_game 模块之外的代码 必须 使用 Guess::new 函数来创建 Guess 实例，从而确保 Guess 的 value 不可能未经 Guess::new 函数中的条件检查。
Next, we implement a method named value that borrows self, doesn’t have any other parameters, and returns an i32. This kind of method is sometimes called a getter because its purpose is to get some data from its fields and return it. This public method is necessary because the value field of the Guess struct is private. It’s important that the value field be private so that code using the Guess struct is not allowed to set value directly: Code outside the guessing_game module must use the Guess::new function to create an instance of Guess, thereby ensuring that there’s no way for a Guess to have a value that hasn’t been checked by the conditions in the Guess::new function.
具有仅处理 1 到 100 之间数字的参数或返回值的函数，随后可以在其签名中声明它接收或返回的是 Guess 而不是 i32，并且其函数体中不需要进行任何额外的检查。
A function that has a parameter or returns only numbers between 1 and 100 could then declare in its signature that it takes or returns a Guess rather than an i32 and wouldn’t need to do any additional checks in its body.
总结
Summary
Rust 的错误处理功能旨在帮助你编写更健壮的代码。panic! 宏表示你的程序处于它无法处理的状态，并允许你告诉进程停止，而不是尝试继续处理无效或不正确的值。Result 枚举利用 Rust 的类型系统来指示操作可能会以你的代码可以恢复的方式失败。你可以使用 Result 来告诉调用你代码的代码，它也需要处理潜在的成功或失败。在适当的情况下使用 panic! 和 Result 将使你的代码在面对不可避免的问题时更加可靠。
Rust’s error-handling features are designed to help you write more robust code. The panic! macro signals that your program is in a state it can’t handle and lets you tell the process to stop instead of trying to proceed with invalid or incorrect values. The Result enum uses Rust’s type system to indicate that operations might fail in a way that your code could recover from. You can use Result to tell code that calls your code that it needs to handle potential success or failure as well. Using panic! and Result in the appropriate situations will make your code more reliable in the face of inevitable problems.
既然你已经看到了标准库在 Option 和 Result 枚举中使用泛型的有用方式，我们将讨论泛型是如何工作的，以及你如何在代码中使用它们。
Now that you’ve seen useful ways that the standard library uses generics with the Option and Result enums, we’ll talk about how generics work and how you can use them in your code.