Восстановимые ошибки с Result
Большинство ошибок не настолько серьёзны, чтобы требовать полной остановки программы. Иногда, когда функция завершается неудачей, это происходит по причине, которую легко интерпретировать и на которую можно отреагировать. Например, если вы пытаетесь открыть файл, и эта операция не удаётся, потому что файл не существует, вы могли бы создать файл вместо завершения процесса.
Вспомните из раздела «Обработка потенциальной ошибки с помощью Result» главы 2, что перечисление Result определено как имеющее два варианта, Ok и Err, следующим образом:
#![allow(unused)]
fn main() {
enum Result<T, E> {
Ok(T),
Err(E),
}
}
T и E — это обобщённые параметры типа: мы обсудим обобщения более подробно в главе 10. То, что нужно знать сейчас, — это то, что T представляет тип значения, которое будет возвращено в случае успеха внутри варианта Ok, а E представляет тип ошибки, которая будет возвращена в случае неудачи внутри варианта Err. Поскольку Result имеет эти обобщённые параметры типа, мы можем использовать тип Result и определённые на нём функции во многих различных ситуациях, где значение успеха и значение ошибки, которые мы хотим вернуть, могут различаться.
Давайте вызовем функцию, которая возвращает значение Result, потому что функция может завершиться неудачей. В листинге 9-3 мы пытаемся открыть файл.
use std::fs::File;
fn main() {
let greeting_file_result = File::open("hello.txt");
}
Возвращаемый тип File::open — это Result<T, E>. Обобщённый параметр T был заполнен реализацией File::open типом значения успеха, std::fs::File, который является дескриптором файла. Тип E, используемый в значении ошибки, — std::io::Error. Этот возвращаемый тип означает, что вызов File::open может завершиться успешно и вернуть дескриптор файла, из которого мы можем читать или в который можем писать. Вызов функции также может завершиться неудачей: например, файл может не существовать, или у нас может не быть разрешения на доступ к файлу. Функции File::open нужен способ сообщить нам, завершилась ли она успешно или неудачей, и одновременно дать нам либо дескриптор файла, либо информацию об ошибке. Эта информация — именно то, что передаёт перечисление Result.
В случае, когда File::open завершается успешно, значение в переменной greeting_file_result будет экземпляром Ok, содержащим дескриптор файла. В случае неудачи значение в greeting_file_result будет экземпляром Err, содержащим больше информации о виде произошедшей ошибки.
Нам нужно добавить к коду в листинге 9-3 действия, зависящие от значения, возвращаемого File::open. Листинг 9-4 показывает один из способов обработки Result с помощью базового инструмента — выражения match, которое мы обсуждали в главе 6.
use std::fs::File;
fn main() {
let greeting_file_result = File::open("hello.txt");
let greeting_file = match greeting_file_result {
Ok(file) => file,
Err(error) => panic!("Problem opening the file: {error:?}"),
};
}
match для обработки вариантов Result, которые могут быть возвращеныОбратите внимание, что, как и перечисление Option, перечисление Result и его варианты были введены в область видимости прелюдией, поэтому нам не нужно указывать Result:: перед вариантами Ok и Err в ветках match.
Когда результат — Ok, этот код вернёт внутреннее значение file из варианта Ok, и затем мы присвоим это значение дескриптора файла переменной greeting_file. После match мы можем использовать дескриптор файла для чтения или записи.
Другая ветка match обрабатывает случай, когда мы получаем значение Err от File::open. В этом примере мы решили вызвать макрос panic!. Если в текущем каталоге нет файла с именем hello.txt и мы запускаем этот код, мы увидим следующий вывод от макроса panic!:
$ cargo run
Compiling error-handling v0.1.0 (file:///projects/error-handling)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.73s
Running `target/debug/error-handling`
thread 'main' (6018048) panicked at src/main.rs:8:23:
Problem opening the file: Os { code: 2, kind: NotFound, message: "No such file or directory" }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
Как обычно, этот вывод говорит нам точно, что пошло не так.
Сопоставление с различными ошибками
Код в листинге 9-4 вызовет panic! независимо от причины, по которой File::open завершился неудачей. Однако мы хотим предпринимать различные действия для разных причин неудачи. Если File::open завершился неудачей, потому что файл не существует, мы хотим создать файл и вернуть дескриптор нового файла. Если File::open завершился неудачей по любой другой причине — например, потому что у нас нет разрешения на открытие файла — мы всё ещё хотим, чтобы код вызвал panic! так же, как в листинге 9-4. Для этого мы добавляем внутреннее выражение match, показанное в листинге 9-5.
use std::fs::File;
use std::io::ErrorKind;
fn main() {
let greeting_file_result = File::open("hello.txt");
let greeting_file = match greeting_file_result {
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:?}"),
},
_ => {
panic!("Problem opening the file: {error:?}");
}
},
};
}
Тип значения, которое File::open возвращает внутри варианта Err, — это io::Error, который является структурой, предоставляемой стандартной библиотекой. Эта структура имеет метод kind, который мы можем вызвать, чтобы получить значение io::ErrorKind. Перечисление io::ErrorKind предоставляется стандартной библиотекой и имеет варианты, представляющие различные виды ошибок, которые могут возникнуть в результате операции io. Вариант, который мы хотим использовать, — ErrorKind::NotFound, который указывает, что файл, который мы пытаемся открыть, ещё не существует. Итак, мы сопоставляем с greeting_file_result, но у нас также есть внутреннее сопоставление с error.kind().
Условие, которое мы хотим проверить во внутреннем сопоставлении, — является ли значение, возвращённое error.kind(), вариантом NotFound перечисления ErrorKind. Если это так, мы пытаемся создать файл с помощью File::create. Однако, поскольку File::create также может завершиться неудачей, нам нужна вторая ветка во внутреннем выражении match. Когда файл не может быть создан, печатается другое сообщение об ошибке. Вторая ветка внешнего match остаётся той же, поэтому программа вызывает панику при любой ошибке, кроме ошибки отсутствия файла.
Альтернативы использованию match с Result<T, E>
Это очень много match! Выражение match очень полезно, но также очень примитивно. В главе 13 вы узнаете о замыканиях, которые используются со многими методами, определёнными для Result<T, E>. Эти методы могут быть более краткими, чем использование match при обработке значений Result<T, E> в вашем коде.
Например, вот другой способ написать ту же логику, что показана в листинге 9-5, на этот раз с использованием замыканий и метода unwrap_or_else:
use std::fs::File;
use std::io::ErrorKind;
fn main() {
let greeting_file = File::open("hello.txt").unwrap_or_else(|error| {
if error.kind() == ErrorKind::NotFound {
File::create("hello.txt").unwrap_or_else(|error| {
panic!("Problem creating the file: {error:?}");
})
} else {
panic!("Problem opening the file: {error:?}");
}
});
}
Хотя этот код имеет то же поведение, что и листинг 9-5, он не содержит никаких выражений match и его чище читать. Вернитесь к этому примеру после того, как прочитаете главу 13, и посмотрите метод unwrap_or_else в документации стандартной библиотеки. Многие другие из этих методов могут очистить огромные, вложенные выражения match, когда вы имеете дело с ошибками.
Сокращения для паники при ошибке
Использование match работает достаточно хорошо, но может быть немного многословным и не всегда хорошо передаёт намерение. Тип Result<T, E> имеет много определённых для него вспомогательных методов для выполнения различных, более конкретных задач. Метод unwrap — это сокращённый метод, реализованный так же, как выражение match, которое мы написали в листинге 9-4. Если значение Result — это вариант Ok, unwrap вернёт значение внутри Ok. Если Result — это вариант Err, unwrap вызовет для нас макрос panic!. Вот пример unwrap в действии:
use std::fs::File;
fn main() {
let greeting_file = File::open("hello.txt").unwrap();
}
Если мы запустим этот код без файла hello.txt, мы увидим сообщение об ошибке от вызова panic!, который делает метод unwrap:
thread 'main' panicked at src/main.rs:4:49:
called `Result::unwrap()` on an `Err` value: Os { code: 2, kind: NotFound, message: "No such file or directory" }
Аналогично, метод expect позволяет нам также выбрать сообщение об ошибке для panic!. Использование expect вместо unwrap и предоставление хороших сообщений об ошибках может передать ваше намерение и облегчить отслеживание источника паники. Синтаксис expect выглядит так:
use std::fs::File;
fn main() {
let greeting_file = File::open("hello.txt")
.expect("hello.txt should be included in this project");
}
Мы используем expect так же, как unwrap: чтобы вернуть дескриптор файла или вызвать макрос panic!. Сообщение об ошибке, используемое expect в его вызове panic!, будет параметром, который мы передаём expect, а не сообщением panic! по умолчанию, которое использует unwrap. Вот как это выглядит:
thread 'main' panicked at src/main.rs:5:10:
hello.txt should be included in this project: Os { code: 2, kind: NotFound, message: "No such file or directory" }
В коде производственного качества большинство растацев выбирают expect, а не unwrap, и дают больше контекста о том, почему операция, как ожидается, всегда будет успешной. Таким образом, если ваши предположения когда-либо окажутся ошибочными, у вас будет больше информации для использования при отладке.
Распространение ошибок
Когда реализация функции вызывает что-то, что может завершиться неудачей, вместо обработки ошибки внутри самой функции вы можете вернуть ошибку вызывающему коду, чтобы он мог решить, что делать. Это известно как распространение ошибки, и это даёт больше контроля вызывающему коду, где может быть больше информации или логики, определяющей, как следует обрабатывать ошибку, чем то, что доступно вам в контексте вашего кода.
Например, листинг 9-6 показывает функцию, которая читает имя пользователя из файла. Если файл не существует или не может быть прочитан, эта функция вернёт эти ошибки коду, который вызвал функцию.
#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};
fn read_username_from_file() -> Result<String, io::Error> {
let username_file_result = File::open("hello.txt");
let mut username_file = match username_file_result {
Ok(file) => file,
Err(e) => return Err(e),
};
let mut username = String::new();
match username_file.read_to_string(&mut username) {
Ok(_) => Ok(username),
Err(e) => Err(e),
}
}
}
matchЭту функцию можно написать намного короче, но мы начнём с того, что сделаем многое вручную, чтобы исследовать обработку ошибок; в конце мы покажем более короткий способ. Давайте сначала посмотрим на возвращаемый тип функции: Result<String, io::Error>. Это означает, что функция возвращает значение типа Result<T, E>, где обобщённый параметр T был заполнен конкретным типом String, а обобщённый тип E был заполнен конкретным типом io::Error.
Если эта функция завершается успешно без каких-либо проблем, код, который вызывает эту функцию, получит значение Ok, содержащее String — имя пользователя, которое эта функция прочитала из файла. Если эта функция столкнётся с какими-либо проблемами, вызывающий код получит значение Err, содержащее экземпляр io::Error, который содержит больше информации о том, в чём были проблемы. Мы выбрали io::Error в качестве возвращаемого типа этой функции, потому что это оказался тип значения ошибки, возвращаемого обеими операциями, которые мы вызываем в теле этой функции и которые могут завершиться неудачей: функцией File::open и методом read_to_string.
Тело функции начинается с вызова функции File::open. Затем мы обрабатываем значение Result с помощью match, аналогичного match в листинге 9-4. Если File::open завершается успешно, дескриптор файла в переменной шаблона file становится значением изменяемой переменной username_file, и функция продолжается. В случае Err вместо вызова panic! мы используем ключевое слово return, чтобы досрочно выйти из функции полностью и передать значение ошибки от File::open, теперь в переменной шаблона e, обратно вызывающему коду как значение ошибки этой функции.
Итак, если у нас есть дескриптор файла в username_file, функция затем создаёт новую String в переменной username и вызывает метод read_to_string для дескриптора файла в username_file, чтобы прочитать содержимое файла в username. Метод read_to_string также возвращает Result, потому что он может завершиться неудачей, даже если File::open завершился успешно. Итак, нам нужен ещё один match для обработки этого Result: если read_to_string завершается успешно, то наша функция завершилась успешно, и мы возвращаем имя пользователя из файла, которое теперь находится в username, обёрнутое в Ok. Если read_to_string завершается неудачей, мы возвращаем значение ошибки так же, как мы возвращали значение ошибки в match, который обрабатывал возвращаемое значение File::open. Однако нам не нужно явно указывать return, потому что это последнее выражение в функции.
Код, который вызывает этот код, затем обработает получение либо значения Ok, содержащего имя пользователя, либо значения Err, содержащего io::Error. Вызывающий код решает, что делать с этими значениями. Если вызывающий код получает значение Err, он может вызвать panic! и аварийно завершить программу, использовать имя пользователя по умолчанию или искать имя пользователя где-то ещё, кроме файла, например. У нас нет достаточно информации о том, что на самом деле пытается сделать вызывающий код, поэтому мы распространяем всю информацию об успехе или ошибке наверх, чтобы он мог обработать её соответствующим образом.
Эта схема распространения ошибок настолько распространена в Rust, что Rust предоставляет оператор вопросительного знака ?, чтобы сделать это проще.
Сокращение с помощью оператора ?
Листинг 9-7 показывает реализацию read_username_from_file, которая имеет ту же функциональность, что и в листинге 9-6, но эта реализация использует оператор ?.
#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};
fn read_username_from_file() -> Result<String, io::Error> {
let mut username_file = File::open("hello.txt")?;
let mut username = String::new();
username_file.read_to_string(&mut username)?;
Ok(username)
}
}
??, размещённый после значения Result, определён так, чтобы работать почти так же, как выражения match, которые мы определили для обработки значений Result в листинге 9-6. Если значение Result — это Ok, значение внутри Ok будет возвращено из этого выражения, и программа продолжится. Если значение — это Err, Err будет возвращён из всей функции, как если бы мы использовали ключевое слово return, так что значение ошибки распространяется на вызывающий код.
Есть разница между тем, что делает выражение match из листинга 9-6, и тем, что делает оператор ?: значения ошибок, для которых был вызван оператор ?, проходят через функцию from, определённую в трейте From в стандартной библиотеке, которая используется для преобразования значений из одного типа в другой. Когда оператор ? вызывает функцию from, полученный тип ошибки преобразуется в тип ошибки, определённый в возвращаемом типе текущей функции. Это полезно, когда функция возвращает один тип ошибки для представления всех способов, которыми функция может завершиться неудачей, даже если части могут завершиться неудачей по многим различным причинам.
Например, мы могли бы изменить функцию read_username_from_file в листинге 9-7, чтобы она возвращала пользовательский тип ошибки с именем OurError, который мы определяем. Если мы также определим impl From<io::Error> for OurError для создания экземпляра OurError из io::Error, то вызовы оператора ? в теле read_username_from_file вызовут from и преобразуют типы ошибок без необходимости добавлять какой-либо дополнительный код в функцию.
В контексте листинга 9-7 ? в конце вызова File::open вернёт значение внутри Ok в переменную username_file. Если возникает ошибка, оператор ? досрочно вернётся из всей функции и передаст любое значение Err вызывающему коду. То же самое относится к ? в конце вызова read_to_string.
Оператор ? устраняет много шаблонного кода и делает реализацию этой функции проще. Мы могли бы даже сократить этот код дальше, объединив вызовы методов сразу после ?, как показано в листинге 9-8.
#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};
fn read_username_from_file() -> Result<String, io::Error> {
let mut username = String::new();
File::open("hello.txt")?.read_to_string(&mut username)?;
Ok(username)
}
}
?Мы переместили создание новой String в username в начало функции; эта часть не изменилась. Вместо создания переменной username_file мы объединили вызов read_to_string непосредственно с результатом File::open("hello.txt")?. У нас всё ещё есть ? в конце вызова read_to_string, и мы всё ещё возвращаем значение Ok, содержащее username, когда и File::open, и read_to_string завершаются успешно, а не возвращаем ошибки. Функциональность снова та же, что в листинге 9-6 и листинге 9-7; это просто другой, более эргономичный способ её написания.
Листинг 9-9 показывает способ сделать это ещё короче с использованием fs::read_to_string.
#![allow(unused)]
fn main() {
use std::fs;
use std::io;
fn read_username_from_file() -> Result<String, io::Error> {
fs::read_to_string("hello.txt")
}
}
fs::read_to_string вместо открытия и затем чтения файлаЧтение файла в строку — довольно распространённая операция, поэтому стандартная библиотека предоставляет удобную функцию fs::read_to_string, которая открывает файл, создаёт новую String, читает содержимое файла, помещает содержимое в эту String и возвращает её. Конечно, использование fs::read_to_string не даёт нам возможности объяснить всю обработку ошибок, поэтому мы сначала сделали это более длинным способом.
Где использовать оператор ?
Оператор ? можно использовать только в функциях, возвращаемый тип которых совместим со значением, к которому применяется ?. Это потому, что оператор ? определён для выполнения досрочного возврата значения из функции, таким же образом, как выражение match, которое мы определили в листинге 9-6. В листинге 9-6 match использовал значение Result, и ветка досрочного возврата возвращала значение Err(e). Возвращаемый тип функции должен быть Result, чтобы он был совместим с этим return.
В листинге 9-10 давайте посмотрим на ошибку, которую мы получим, если используем оператор ? в функции main с возвращаемым типом, несовместимым с типом значения, к которому мы применяем ?.
use std::fs::File;
fn main() {
let greeting_file = File::open("hello.txt")?;
}
? в функции main, которая возвращает (), не скомпилируется.Этот код открывает файл, что может завершиться неудачей. Оператор ? следует за значением Result, возвращённым File::open, но эта функция main имеет возвращаемый тип (), а не Result. Когда мы компилируем этот код, мы получаем следующее сообщение об ошибке:
$ cargo run
Compiling error-handling v0.1.0 (file:///projects/error-handling)
error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`)
--> src/main.rs:4:48
|
3 | fn main() {
| --------- this function should return `Result` or `Option` to accept `?`
4 | let greeting_file = File::open("hello.txt")?;
| ^ cannot use the `?` operator in a function that returns `()`
|
help: consider adding return type
|
3 ~ fn main() -> Result<(), Box<dyn std::error::Error>> {
4 | let greeting_file = File::open("hello.txt")?;
5 + Ok(())
|
For more information about this error, try `rustc --explain E0277`.
error: could not compile `error-handling` (bin "error-handling") due to 1 previous error
Эта ошибка указывает на то, что нам разрешено использовать оператор ? только в функции, которая возвращает Result, Option или другой тип, реализующий FromResidual.
Чтобы исправить ошибку, у вас есть два варианта. Один из вариантов — изменить возвращаемый тип вашей функции, чтобы он был совместим со значением, к которому вы применяете оператор ?, если у вас нет ограничений, препятствующих этому. Другой вариант — использовать match или один из методов Result<T, E> для обработки Result<T, E> любым подходящим способом.
Сообщение об ошибке также упомянуло, что ? можно использовать со значениями Option<T>. Как и при использовании ? с Result, вы можете использовать ? с Option только в функции, которая возвращает Option. Поведение оператора ? при вызове с Option<T> аналогично его поведению при вызове с Result<T, E>: если значение — None, None будет досрочно возвращён из функции в этот момент. Если значение — Some, значение внутри Some является результирующим значением выражения, и функция продолжается. Листинг 9-11 содержит пример функции, которая находит последний символ первой строки в заданном тексте.
fn last_char_of_first_line(text: &str) -> Option<char> {
text.lines().next()?.chars().last()
}
fn main() {
assert_eq!(
last_char_of_first_line("Hello, world\nHow are you today?"),
Some('d')
);
assert_eq!(last_char_of_first_line(""), None);
assert_eq!(last_char_of_first_line("\nhi"), None);
}
? со значением Option<T>Эта функция возвращает Option<char>, потому что возможно, что там есть символ, но также возможно, что его нет. Этот код принимает аргумент среза строки text и вызывает для него метод lines, который возвращает итератор по строкам в строке. Поскольку эта функция хочет исследовать первую строку, она вызывает next для итератора, чтобы получить первое значение из итератора. Если text — пустая строка, этот вызов next вернёт None, и в этом случае мы используем ?, чтобы остановиться и вернуть None из last_char_of_first_line. Если text не пустая строка, next вернёт значение Some, содержащее срез строки первой строки в text.
? извлекает срез строки, и мы можем вызвать chars для этого среза строки, чтобы получить итератор по его символам. Нас интересует последний символ в этой первой строке, поэтому мы вызываем last, чтобы вернуть последний элемент в итераторе. Это Option, потому что возможно, что первая строка — пустая строка; например, если text начинается с пустой строки, но имеет символы на других строках, как в "\nhi". Однако, если в первой строке есть последний символ, он будет возвращён в варианте Some. Оператор ? в середине даёт нам краткий способ выразить эту логику, позволяя нам реализовать функцию в одну строку. Если бы мы не могли использовать оператор ? с Option, нам пришлось бы реализовать эту логику с помощью большего количества вызовов методов или выражения match.
Обратите внимание, что вы можете использовать оператор ? с Result в функции, которая возвращает Result, и вы можете использовать оператор ? с Option в функции, которая возвращает Option, но вы не можете смешивать их. Оператор ? не будет автоматически преобразовывать Result в Option или наоборот; в таких случаях вы можете использовать такие методы, как метод ok для Result или метод ok_or для Option, чтобы выполнить преобразование явно.
До сих пор все функции main, которые мы использовали, возвращают (). Функция main особенная, потому что она является точкой входа и выхода исполняемой программы, и есть ограничения на то, каким может быть её возвращаемый тип, чтобы программа вела себя как ожидается.
К счастью, main также может возвращать Result<(), E>. В листинге 9-12 есть код из листинга 9-10, но мы изменили возвращаемый тип main на Result<(), Box<dyn Error>> и добавили возвращаемое значение Ok(()) в конец. Этот код теперь скомпилируется.
use std::error::Error;
use std::fs::File;
fn main() -> Result<(), Box<dyn Error>> {
let greeting_file = File::open("hello.txt")?;
Ok(())
}
main для возврата Result<(), E> позволяет использовать оператор ? со значениями Result.Тип Box<dyn Error> — это трейт-объект, о котором мы поговорим в разделе «Использование трейт-объектов для абстрагирования над общим поведением» главы 18. Пока вы можете читать Box<dyn Error> как «любой вид ошибки». Использование ? со значением Result в функции main с типом ошибки Box<dyn Error> разрешено, потому что это позволяет досрочно вернуть любое значение Err. Хотя тело этой функции main будет возвращать только ошибки типа std::io::Error, указав Box<dyn Error>, эта сигнатура останется правильной, даже если в тело main будет добавлен код, возвращающий другие ошибки.
Когда функция main возвращает Result<(), E>, исполняемый файл завершится со значением 0, если main вернёт Ok(()), и завершится с ненулевым значением, если main вернёт значение Err. Исполняемые файлы, написанные на C, возвращают целые числа при выходе: программы, которые завершаются успешно, возвращают целое число 0, а программы, которые завершаются с ошибкой, возвращают какое-то целое число, отличное от 0. Rust также возвращает целые числа из исполняемых файлов, чтобы быть совместимым с этой конвенцией.
Функция main может возвращать любые типы, реализующие трейт std::process::Termination, который содержит функцию report, возвращающую ExitCode. Обратитесь к документации стандартной библиотеки для получения дополнительной информации о реализации трейта Termination для ваших собственных типов.
Теперь, когда мы обсудили детали вызова panic! или возврата Result, давайте вернёмся к теме того, как решить, какой из них уместно использовать в каких случаях.