Вызывать panic! или не вызывать panic!
Итак, как решить, когда следует вызывать panic!, а когда возвращать
Result? Когда код паникует, восстановиться невозможно. Можно вызывать panic!
для любой ошибочной ситуации, независимо от того, есть ли возможный способ восстановления, но
тогда вы принимаете решение о том, что ситуация невосстановима, от имени
вызывающего кода. Когда вы решаете вернуть значение Result, вы даёте
вызывающему коду варианты. Вызывающий код может решить попытаться восстановиться
способом, подходящим для его ситуации, или решить, что значение Err
в данном случае невосстановимо, поэтому он может вызвать panic! и превратить вашу
восстановимую ошибку в невосстановимую. Следовательно, возврат Result —
хороший выбор по умолчанию, когда вы определяете функцию, которая может завершиться неудачей.
В таких ситуациях, как примеры, прототипный код и тесты, уместнее
писать код, который паникует, вместо возврата Result. Давайте
разберёмся почему, а затем обсудим ситуации, в которых компилятор не может определить, что
сбой невозможен, но вы как человек можете. Глава завершится
некоторыми общими рекомендациями о том, как решить, стоит ли паниковать в библиотечном коде.
Примеры, прототипный код и тесты
Когда вы пишете пример для иллюстрации какой-либо концепции, включение также
надёжного кода обработки ошибок может сделать пример менее понятным. В примерах
подразумевается, что вызов такого метода, как unwrap, который может паниковать, является
заглушкой для того, как вы хотели бы, чтобы ваше приложение обрабатывало ошибки, что может
отличаться в зависимости от того, что делает остальной ваш код.
Аналогично, методы unwrap и expect очень удобны, когда вы
создаёте прототип и ещё не готовы решить, как обрабатывать ошибки. Они оставляют
чёткие маркеры в вашем коде для момента, когда вы будете готовы сделать программу более
надёжной.
Если вызов метода завершается неудачей в тесте, вы хотели бы, чтобы весь тест завершился неудачей, даже если
этот метод не является тестируемой функциональностью. Поскольку panic! — это способ пометить тест
как неудачный, вызов unwrap или expect — это именно то, что должно
происходить.
Когда у вас больше информации, чем у компилятора
Также было бы уместно вызывать expect, когда у вас есть какая-то другая логика,
которая гарантирует, что Result будет иметь значение Ok, но эта логика
не является чем-то, что понимает компилятор. У вас всё ещё будет значение Result, которое
нужно обработать: какая бы операция ни вызывалась, она всё ещё имеет возможность
завершиться неудачей в общем случае, даже если это логически невозможно в вашей конкретной
ситуации. Если вы можете убедиться, вручную проверив код, что у вас никогда
не будет варианта Err, вполне допустимо вызвать expect и задокументировать
причину, по которой вы считаете, что у вас никогда не будет варианта Err, в тексте аргумента.
Вот пример:
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, и компилятор всё ещё
заставит нас обработать Result так, как будто вариант Err возможен,
потому что компилятор недостаточно умён, чтобы увидеть, что эта строка всегда является
корректным IP-адресом. Если бы строка IP-адреса происходила от пользователя, а не была
жёстко задана в программе, и, следовательно, имела возможность сбоя,
мы бы определённо хотели обработать Result более надёжным способом.
Упоминание предположения, что этот IP-адрес жёстко задан, подтолкнёт нас к тому, чтобы
заменить expect на лучший код обработки ошибок, если в будущем нам потребуется получить
IP-адрес из какого-либо другого источника.
Рекомендации по обработке ошибок
Желательно, чтобы код паниковал, когда есть вероятность, что код может оказаться в некорректном состоянии. В этом контексте некорректное состояние — это когда какое-то предположение, гарантия, контракт или инвариант нарушены, например, когда в код передаются недопустимые значения, противоречивые значения или отсутствующие значения, плюс одно или более из следующих условий:
- Некорректное состояние — это что-то неожиданное, в отличие от чего-то, что вероятно будет случаться время от времени, например, пользователь вводит данные в неверном формате.
- Ваш код после этой точки должен полагаться на то, что он не находится в этом некорректном состоянии, а не проверять наличие проблемы на каждом шаге.
- Нет хорошего способа закодировать эту информацию в используемых типах. Мы проработаем пример того, что мы имеем в виду, в разделе «Кодирование состояний и поведения как типов» в главе 18.
Если кто-то вызывает ваш код и передаёт значения, которые не имеют смысла, лучше всего
вернуть ошибку, если это возможно, чтобы пользователь библиотеки мог решить,
что делать в этом случае. Однако в случаях, когда продолжение может быть
небезопасным или вредоносным, лучшим выбором может быть вызов panic! и предупреждение
человека, использующего вашу библиотеку, об ошибке в его коде, чтобы он мог исправить её
во время разработки. Аналогично, panic! часто уместен, если вы вызываете
внешний код, который находится вне вашего контроля и возвращает недопустимое состояние, которое вы
не можете исправить.
Однако, когда сбой ожидаем, уместнее вернуть Result,
чем вызывать panic!. Примеры включают парсер, которому переданы некорректные
данные, или HTTP-запрос, возвращающий статус, указывающий на достижение лимита
запросов. В этих случаях возврат Result указывает на то, что сбой является
ожидаемой возможностью, которую вызывающий код должен решить, как обработать.
Когда ваш код выполняет операцию, которая может подвергнуть пользователя риску, если она
вызвана с недопустимыми значениями, ваш код должен сначала проверить, что значения допустимы,
и паниковать, если значения недопустимы. Это в основном по соображениям безопасности:
попытка работать с недопустимыми данными может сделать ваш код уязвимым.
Это основная причина, по которой стандартная библиотека вызовет panic!, если вы попытаетесь
выполнить доступ к памяти за пределами допустимого диапазона: попытка доступа к памяти, которая не принадлежит
текущей структуре данных, является распространённой проблемой безопасности. Функции часто имеют
контракты: их поведение гарантируется только в том случае, если входные данные соответствуют определённым
требованиям. Паника при нарушении контракта имеет смысл, потому что нарушение
контракта всегда указывает на ошибку на стороне вызывающего кода, и это не тот вид
ошибки, которую вызывающий код должен явно обрабатывать. На самом деле нет
разумного способа для вызывающего кода восстановиться; вызывающим программистам нужно
исправить код. Контракты функции, особенно когда нарушение
вызовет панику, должны быть объяснены в документации API функции.
Однако наличие множества проверок ошибок во всех функциях было бы многословно
и раздражающе. К счастью, можно использовать систему типов Rust (и, следовательно, проверку типов,
выполняемую компилятором), чтобы выполнить многие проверки за вас. Если ваша
функция имеет параметр определённого типа, можно продолжать логику вашего кода,
зная, что компилятор уже обеспечил наличие допустимого
значения. Например, если у вас есть тип, а не Option, ваша программа
ожидает что-то, а не ничего. Тогда ваш код не должен
обрабатывать два случая для вариантов Some и None: у него будет только один
случай, когда значение определённо есть. Код, пытающийся передать ничего в вашу
функцию, даже не скомпилируется, поэтому вашей функции не нужно проверять этот
случай во время выполнения. Другой пример — использование беззнакового целочисленного типа, такого как
u32, который гарантирует, что параметр никогда не будет отрицательным.
Пользовательские типы для проверки
Давайте разовьём идею использования системы типов Rust для обеспечения наличия допустимого значения на один шаг дальше и рассмотрим создание пользовательского типа для проверки. Вспомните игру-угадайку из главы 2, в которой наш код просил пользователя угадать число от 1 до 100. Мы никогда не проверяли, что догадка пользователя находится между этими числами, прежде чем сравнивать её с нашим секретным числом; мы только проверяли, что догадка положительна. В этом случае последствия были не очень серьёзными: наш вывод «Слишком много» или «Слишком мало» всё равно был бы правильным. Но было бы полезным улучшением направлять пользователя к допустимым догадкам и иметь различное поведение, когда пользователь угадывает число вне диапазона, по сравнению с ситуацией, когда пользователь вводит, например, буквы.
Одним из способов сделать это было бы разобрать догадку как i32 вместо только
u32, чтобы разрешить потенциально отрицательные числа, а затем добавить проверку на
нахождение числа в диапазоне, вот так:
use std::cmp::Ordering;
use std::io;
use rand::prelude::*;
fn main() {
println!("Guess the number!");
let secret_number = rand::rng().random_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.
Однако это не идеальное решение: если было бы абсолютно критично, чтобы программа работала только со значениями от 1 до 100, и у неё было бы много функций с этим требованием, наличие такой проверки в каждой функции было бы утомительным (и могло бы повлиять на производительность).
Вместо этого можно создать новый тип в выделенном модуле и поместить проверки
в функцию для создания экземпляра типа вместо повторения
проверок повсюду. Таким образом, функциям безопасно использовать новый тип
в своих сигнатурах и уверенно использовать значения, которые они получают. Листинг 9-13
показывает один из способов определения типа Guess, который создаст экземпляр
Guess только в том случае, если функция new получит значение от 1 до 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
}
}
}
Guess, который продолжит работу только со значениями от 1 до 100Обратите внимание, что этот код в src/guessing_game.rs зависит от добавления объявления модуля
mod guessing_game; в src/lib.rs, которое мы здесь не показали.
Внутри файла этого нового модуля мы определяем структуру с именем Guess, у которой
есть поле с именем value, содержащее i32. Здесь будет
храниться число.
Затем мы реализуем связанную функцию с именем new для Guess, которая создаёт
экземпляры значений Guess. Функция new определена так, чтобы иметь один
параметр с именем value типа i32 и возвращать Guess. Код в
теле функции new проверяет value, чтобы убедиться, что оно находится между 1 и 100.
Если value не проходит эту проверку, мы вызываем panic!, что предупредит
программиста, пишущего вызывающий код, что у него есть ошибка, которую нужно
исправить, потому что создание Guess со значением value вне этого диапазона
нарушило бы контракт, на который опирается Guess::new. Условия, при которых
Guess::new может паниковать, должны быть обсуждены в его публичной
документации API; мы рассмотрим соглашения документирования, указывающие на возможность
panic!, в документации API, которую вы создаёте в главе 14. Если
value проходит проверку, мы создаём новый Guess с его полем value, установленным
в параметр value, и возвращаем Guess.
Затем мы реализуем метод с именем value, который заимствует self, не имеет никаких
других параметров и возвращает i32. Такой метод иногда называют
геттером, потому что его назначение — получить некоторые данные из полей и вернуть
их. Этот публичный метод необходим, потому что поле value структуры Guess
является приватным. Важно, чтобы поле value было приватным, чтобы
код, использующий структуру Guess, не мог напрямую устанавливать value: код
вне модуля guessing_game должен использовать функцию Guess::new, чтобы
создать экземпляр Guess, тем самым гарантируя, что не будет способа получить
Guess со значением value, не проверенным условиями в
функции Guess::new.
Функция, которая имеет параметр или возвращает только числа от 1 до 100, могла бы
затем объявить в своей сигнатуре, что она принимает или возвращает Guess, а не
i32, и не нуждалась бы в дополнительных проверках в своём теле.
Итоги
Возможности обработки ошибок Rust предназначены для того, чтобы помочь писать более надёжный код.
Макрос panic! сигнализирует, что программа находится в состоянии, которое она не может
обработать, и позволяет сказать процессу остановиться вместо попытки продолжить работу с недопустимыми или
некорректными значениями. Перечисление Result использует систему типов Rust, чтобы указать, что
операции могут завершиться неудачей способом, от которого ваш код может
восстановиться. Можно использовать Result, чтобы сообщить коду, который вызывает ваш код, что ему нужно
обрабатывать как потенциальный успех, так и сбой. Использование panic! и Result в подходящих
ситуациях сделает ваш код более надёжным перед лицом неизбежных проблем.
Теперь, когда вы увидели полезные способы использования стандартной библиотекой обобщённых типов с
перечислениями Option и Result, мы поговорим о том, как работают обобщённые типы и как вы
можете использовать их в своём коде.