Обработка ошибок
Ошибки — ожидаемое состояние системы. UI должен обрабатывать их предсказуемо, без падения приложения и без утечки технических деталей. Обработка ошибок является неотъемлемой частью архитектуры интерфейса и проектируется на этапе разработки, а не добавляется после релиза.
Общие принципы
MUST
- Ошибка НЕ приводит к крашу приложения — любая ошибка должна быть перехвачена и обработана на соответствующем уровне.
- UI корректно обрабатывает ошибочные состояния — для каждого типа ошибки определен паттерн отображения.
- Обработка ошибок — часть архитектуры интерфейса — проектируется на этапе разработки функционала, а не добавляется постфактум.
- Ошибки нормализуются в единый формат — UI работает только с унифицированной моделью ошибки.
- Функции с возможной ошибкой возвращают
Result<T, AppError>— вместо неконтролируемыхthrow/catch. Ошибка явна на каждом шаге от API до UI.
SHOULD
- Логировать ошибки в систему мониторинга — для анализа и улучшения системы (Sentry, LogRocket и т.д.).
- Группировать похожие ошибки — чтобы не спамить пользователя множеством одинаковых сообщений.
FORBIDDEN
- Показывать stack trace пользователю — технические детали не должны быть видны в UI.
- Отображать raw сообщения из back-end API — сообщения должны быть локализованы и адаптированы.
- Раскрывать технические детали — внутренние имена переменных, пути к файлам, версии библиотек не должны попадать в пользовательский интерфейс.
Уровни отображения ошибок
Ошибка показывается на уровне UI, соответствующем области влияния. Выбор правильного уровня критичен для UX.
MUST
- Выбирать минимально достаточный уровень — ошибка должна отображаться на самом узком уровне, который позволяет пользователю понять и исправить ситуацию.
- Эскалировать уровень только при невозможности локального восстановления — если ошибка не может быть решена на текущем уровне, она поднимается выше.
- Сохранять контекст при эскалации — пользователь должен понимать, что произошло и почему произошла эскалация.
SHOULD
- Предоставлять действия для восстановления — кнопка "Повторить", "Обновить", "Вернуться" в зависи мости от контекста.
- Показывать прогресс при повторных попытках — если система автоматически пытается восстановиться.
Примеры распределения по уровням
| Уровень | Где показываем | Примеры ситуаций | UI паттерн |
|---|---|---|---|
| Локальный | Рядом с элементом | Неверный формат email, пустое обязательное поле, некорректная дата | Inline error, Helper text |
| Модульный | Внутри блока/виджета | Ошибка загрузки списка товаров, недоступность виджета статистики | Local Error Boundary, Empty state с сообщением |
| Глобальный | Layout/страница целиком | Просроченная сессия (401), отсутствие прав доступа (403), критическая ошибка рендеринга | Global Error Boundary, Modal, Redirect |
Структура документации
Документация по обработке ошибок состоит из следующих разделов:
- Классификация ошибок — категории, статусы, единая модель данных, паттерн Result
- UI-паттерны — error boundaries, inline errors, toast, snackbar
- Надёжность и UX — retry-логика, сохранение пользовательского ввода, локализация, упрощения для MVP
- Процедуры контроля — чек-лист для code review