Обработка ошибок

Unpoly — это JavaScript-библиотека, ориентированная на плавное обновление частей страницы без полной перезагрузки. Одним из важных аспектов работы с Unpoly является корректная обработка ошибок, возникающих при загрузке фрагментов, выполнении запросов и обработке серверных ответов. Ошибки могут быть связаны как с сетью, так и с логикой приложения, поэтому библиотека предоставляет гибкие механизмы для их перехвата и управления.

События ошибок

Unpoly генерирует специальные события, которые позволяют реагировать на сбои запросов. Основные события:

up:request:error — возникает при сетевой ошибке или если сервер вернул код состояния HTTP 4xx или 5xx.
up:fragment:error — срабатывает, когда ошибка произошла именно при замене фрагмента.
up:fail — глобальное событие для всех неудачных запросов.

Пример использования:

document.addEventListener('up:request:error', function(event) {
    console.error('Ошибка запроса:', event.detail.request);
});

event.detail содержит объект с подробной информацией о неудавшемся запросе:

request.url — URL запроса
request.method — HTTP-метод
request.response — объект ответа, если он получен
request.status — код состояния HTTP

Использование этих данных позволяет реализовать адаптивную обработку ошибок, включая повторные запросы или показ сообщений пользователю.

Проверка статусов ответа

Unpoly по умолчанию рассматривает любой код HTTP ≥ 400 как ошибку. Однако поведение можно изменять с помощью опции validate в конфигурации запроса:

up.link('.load-fragment', {
    validate: function(request) {
        return request.status !== 422; // 422 не считается ошибкой
    }
});

Это особенно полезно для обработки ошибок валидации формы на сервере, когда необходимо получить ответ без генерации событий ошибок.

Перехват и кастомизация ошибок

Для более точного контроля можно использовать up.on('up:request:error', callback). Например, можно показать пользователю модальное окно с сообщением:

up.on('up:request:error', function(event) {
    const status = event.detail.request.status;
    let message;

    switch(status) {
        case 404:
            message = 'Запрошенная страница не найдена';
            break;
        case 500:
            message = 'Внутренняя ошибка сервера';
            break;
        default:
            message = 'Произошла неизвестная ошибка';
    }

    up.toast(message, { type: 'error' });
});

Такой подход позволяет отделить обработку ошибок от логики обновления контента.

Ошибки при замене фрагмента

Даже если запрос выполнен успешно, замена части страницы может завершиться ошибкой. Например, если целевой селектор не найден или сервер вернул некорректный HTML. В таких случаях срабатывает событие up:fragment:error.

Пример:

document.addEventListener('up:fragment:error', function(event) {
    console.warn('Ошибка обновления фрагмента:', event.detail.fragment);
});

Объект event.detail.fragment содержит информацию о целевом фрагменте и полученном контенте.

Глобальная обработка ошибок

Для приложений, где требуется централизованный контроль, можно подписываться на глобальное событие up:fail:

up.on('up:fail', function(event) {
    console.log('Глобальная ошибка Unpoly', event.detail.request.url);
});

Это позволяет вести логирование всех сбоев или отправлять отчеты на сервер.

Пользовательские обработчики для форм

Ошибки часто возникают при отправке форм. Unpoly поддерживает up:form:submission:failed, которое срабатывает, если сервер вернул ошибку при отправке формы:

document.addEventListener('up:form:submission:failed', function(event) {
    const form = event.target;
    const errors = event.detail.response.body; 
    console.error('Ошибка формы:', errors);
});

Можно динамически подсвечивать поля с ошибками или показывать сообщения в контексте формы без перезагрузки страницы.

Логирование и отладка

Для отладки полезно использовать встроенные методы up.log.enable() и up.log.disable():

up.log.enable(); // Включает подробное логирование всех запросов и ошибок

Комбинируя это с обработчиками событий ошибок, можно легко анализировать поведение приложения в реальном времени.