BackgroundSyncPlugin

BackgroundSyncPlugin является мощным инструментом библиотеки Workbox, предназначенным для обеспечения надёжной доставки запросов, которые не были успешно выполнены из-за отсутствия сети. Этот плагин особенно полезен для Progressive Web Apps (PWA), где требуется гарантировать, что данные, отправленные пользователем, будут доставлены на сервер даже при временном отсутствии интернет-соединения.

Основные принципы работы

BackgroundSyncPlugin работает по принципу очереди. Когда запрос, защищённый этим плагином, не может быть выполнен (например, сетевой запрос возвращает ошибку из-за отсутствия подключения), он помещается в очередь и автоматически повторяется, когда сеть снова становится доступной. Плагин использует Service Worker для управления этой очередью, что обеспечивает асинхронность и надёжность.

Создание экземпляра плагина

Для начала необходимо импортировать и создать экземпляр плагина:

import { BackgroundSyncPlugin } from 'workbox-background-sync';

const bgSyncPlugin = new BackgroundSyncPlugin('myQueueName', {
  maxRetentionTime: 24 * 60 // Время хранения запросов в очереди в минутах
});

Параметры конструктора:

  • queueName — уникальное имя очереди. Позволяет разделять очереди для разных типов запросов.
  • options.maxRetentionTime — максимальное время хранения запроса в очереди в минутах. После истечения этого времени запрос удаляется.

Интеграция с Workbox Routing

Для использования BackgroundSyncPlugin вместе с Workbox Routing создаются стратегии кэширования, которые применяют плагин к определённым маршрутам:

import { registerRoute } from 'workbox-routing';
import { NetworkOnly } from 'workbox-strategies';

registerRoute(
  /\/api\/.*\/*.json/,
  new NetworkOnly({
    plugins: [bgSyncPlugin]
  }),
  'POST'
);

Здесь стратегия NetworkOnly используется для POST-запросов к API. Если сеть недоступна, запросы автоматически попадают в очередь BackgroundSyncPlugin.

Очередь и события

BackgroundSyncPlugin предоставляет события для отслеживания состояния запросов в очереди:

  • queueDidReplay — срабатывает после успешной отправки всех запросов из очереди.
  • queueDidReplayEntry — срабатывает после успешной отправки конкретного запроса.
  • queueDidFailEntry — срабатывает при неудачной попытке повторной отправки запроса.
  • queueDidRequestReplay — срабатывает при попытке отправки очереди.

Пример подписки на события:

bgSyncPlugin.queue.addEventListener('queueDidReplay', (event) => {
  console.log('Все запросы из очереди успешно отправлены', event);
});

bgSyncPlugin.queue.addEventListener('queueDidFailEntry', (event) => {
  console.log('Ошибка отправки запроса:', event.entry);
});

Настройка повторных попыток

BackgroundSyncPlugin позволяет настраивать количество попыток повторной отправки и интервалы между ними. По умолчанию используется экспоненциальная задержка. Для более тонкой настройки можно использовать workbox-background-sync вместе с кастомными обработчиками:

import { Queue } from 'workbox-background-sync';

const queue = new Queue('customQueue', {
  maxRetentionTime: 24 * 60,
  onSync: async ({ queue }) => {
    let entry;
    while ((entry = await queue.shiftRequest())) {
      try {
        await fetch(entry.request);
      } catch (error) {
        await queue.unshiftRequest(entry);
        break;
      }
    }
  }
});

В этом примере используется метод shiftRequest() для последовательной обработки запросов. В случае ошибки запрос возвращается в начало очереди с помощью unshiftRequest().

Совместимость с различными методами HTTP

BackgroundSyncPlugin может использоваться не только для POST, но и для других методов, требующих надёжной доставки данных: PUT, PATCH, DELETE. Однако GET-запросы обычно не используют Background Sync, так как они не изменяют состояние на сервере и их повторная отправка может быть излишней.

Ограничения и рекомендации

  • Плагин работает только в Service Worker и не будет работать в обычном скрипте на странице.
  • Очередь хранится в IndexedDB. При больших объёмах данных необходимо контролировать размер очереди.
  • Не рекомендуется использовать для запросов, где критична мгновенная доставка, так как Background Sync срабатывает только после восстановления сети.

Практическое использование

BackgroundSyncPlugin незаменим для приложений, работающих с формами, чатами или другими функциями, требующими надёжной передачи данных при нестабильном соединении. В комбинации с стратегиями кэширования Workbox он обеспечивает баланс между отзывчивостью интерфейса и гарантией доставки данных.

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

Оглавление