Workbox-Routing

Ein Service Worker kann Netzwerkanfragen für eine Seite abfangen. Sie kann dem Browser mit im Cache gespeicherten Inhalten, Inhalten aus dem Netzwerk oder Inhalten antworten, die vom Service Worker generiert wurden.

workbox-routing ist ein Modul, mit dem diese Anfragen einfach an verschiedene Funktionen weitergeleitet werden können, die Antworten liefern.

So wird das Routing durchgeführt

Wenn eine Netzwerkanfrage ein Service Worker-Abrufereignis verursacht, versucht workbox-routing, über die angegebenen Routen und Handler auf die Anfrage zu antworten.

Die wichtigsten Punkte aus den obigen Angaben:

• Die Methode einer Anfrage ist wichtig. Standardmäßig werden Routen für GET-Anfragen registriert. Wenn Sie andere Arten von Anfragen abfangen möchten, müssen Sie die Methode angeben.

• Die Reihenfolge der Routenregistrierung ist wichtig. Wenn mehrere Routen registriert sind, die eine Anfrage verarbeiten können, wird die zuerst registrierte Route zum Antworten auf die Anfrage verwendet.

Es gibt verschiedene Möglichkeiten, eine Route zu registrieren. Sie können Callbacks, reguläre Ausdrücke oder Routeninstanzen verwenden.

Abgleich und Verarbeitung in Routen

Eine "Route" in der Arbeitsbox besteht aus nicht mehr als zwei Funktionen: einer Abgleichfunktion, um zu bestimmen, ob die Route einer Anfrage entsprechen soll, und einer Verarbeitungsfunktion, die die Anfrage verarbeiten und mit einer Antwort antworten sollte.

Workbox enthält einige Hilfsprogramme, die den Abgleich und die Verarbeitung für Sie durchführen. Wenn Sie jedoch jemals ein anderes Verhalten wünschen, ist das Schreiben einer benutzerdefinierten Abgleich- und Handler-Funktion die beste Option.

Einer Abgleich-Callback-Funktion werden ein ExtendableEvent-, Request- und ein URL-Objekt übergeben, das Sie abgleichen können, indem Sie einen Wahrheitswert zurückgeben. Für ein einfaches Beispiel könnten Sie den Abgleich mit einer bestimmten URL durchführen:

const matchCb = ({url, request, event}) => {
  return url.pathname === '/special/url';
};

Die meisten Anwendungsfälle können durch Untersuchung / Tests von url oder request abgedeckt werden.

Eine Handler-Callback-Funktion erhält dasselbe ExtendableEvent-, Request- und URL-Objekt sowie einen params-Wert. Dies ist der Wert, der von der Abgleichfunktion zurückgegeben wird.

const handlerCb = async ({url, request, event, params}) => {
  const response = await fetch(request);
  const responseBody = await response.text();
  return new Response(`${responseBody} <!-- Look Ma. Added Content. -->`, {
    headers: response.headers,
  });
};

Dein Handler muss ein Promise zurückgeben, das zu einem Response aufgelöst wird. In diesem Beispiel verwenden wir async und await. Intern wird der Rückgabewert Response in ein Promise umgewandelt.

Sie können diese Callbacks so registrieren:

import {registerRoute} from 'workbox-routing';

registerRoute(matchCb, handlerCb);

Die einzige Einschränkung besteht darin, dass der „Übereinstimmung“-Callback synchron den Wahrheitswert zurückgeben muss. Sie können keine asynchronen Aufgaben ausführen. Der Grund dafür ist, dass Router synchron auf das Abrufereignis reagieren muss oder einen Durchfall auf andere Abrufereignisse zulassen muss.

Normalerweise verwendet der Callback „handler“ eine der von workbox-strategies bereitgestellten Strategien, wie hier gezeigt:

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

registerRoute(matchCb, new StaleWhileRevalidate());

Auf dieser Seite konzentrieren wir uns auf workbox-routing. Weitere Informationen zu diesen Strategien für Workbox-Strategien finden Sie hier.

Registrieren einer Route mit regulären Ausdrücken

Häufig wird ein regulärer Ausdruck anstelle eines Callbacks für Übereinstimmung verwendet. Mit Workbox ist dies ganz einfach:

import {registerRoute} from 'workbox-routing';

registerRoute(new RegExp('/styles/.*\\.css'), handlerCb);

Bei Anfragen vom gleichen Ursprung stimmt dieser reguläre Ausdruck überein, solange die URL der Anfrage mit dem regulären Ausdruck übereinstimmt.

• https://example.com/styles/main.css
• https://example.com/styles/nested/file.css
• https://example.com/nested/styles/directory.css

Bei ursprungsübergreifenden Anfragen müssen die regulären Ausdrücke jedoch mit dem Anfang der URL übereinstimmen. Der Grund dafür ist, dass Sie wahrscheinlich mit dem regulären Ausdruck new RegExp('/styles/.*\\.css') CSS-Dateien von Drittanbietern abgleichen möchten.

• https://cdn.third-party-site.com/styles/main.css
• https://cdn.third-party-site.com/styles/nested/file.css
• https://cdn.third-party-site.com/nested/styles/directory.css

Wenn Sie dieses Verhalten erwünscht haben, müssen Sie lediglich darauf achten, dass der reguläre Ausdruck mit dem Anfang der URL übereinstimmt. Wenn wir die Anfragen für https://cdn.third-party-site.com abgleichen möchten, können wir den regulären Ausdruck new RegExp('https://cdn\\.third-party-site\\.com.*/styles/.*\\.css') verwenden.

• https://cdn.third-party-site.com/styles/main.css
• https://cdn.third-party-site.com/styles/nested/file.css
• https://cdn.third-party-site.com/nested/styles/directory.css

Wenn Sie sowohl lokale als auch Drittanbieter-Objekte abgleichen möchten, können Sie am Anfang des regulären Ausdrucks einen Platzhalter verwenden. Dies sollte jedoch mit Vorsicht erfolgen, damit es in Ihrer Webanwendung nicht zu unerwartetem Verhalten kommt.

Registrieren einer Navigationsroute

Wenn Ihre Website eine Single-Page-App ist, können Sie einen NavigationRoute verwenden, um eine bestimmte Antwort auf alle Navigationsanfragen zurückzugeben.

import {createHandlerBoundToURL} from 'workbox-precaching';
import {NavigationRoute, registerRoute} from 'workbox-routing';

// This assumes /app-shell.html has been precached.
const handler = createHandlerBoundToURL('/app-shell.html');
const navigationRoute = new NavigationRoute(handler);
registerRoute(navigationRoute);

Immer wenn ein Nutzer Ihre Website im Browser aufruft, ist die Anfrage für die Seite eine Navigationsanfrage, die an die im Cache gespeicherte Seite /app-shell.html gesendet wird. Hinweis: Die Seite sollte über workbox-precaching oder durch deinen eigenen Installationsschritt im Cache gespeichert werden.

Standardmäßig werden damit alle Navigationsanfragen beantwortet. Wenn die Antwort auf eine Untergruppe von URLs eingeschränkt werden soll, können Sie mit den Optionen allowlist und denylist einschränken, welche Seiten dieser Route entsprechen.

import {createHandlerBoundToURL} from 'workbox-precaching';
import {NavigationRoute, registerRoute} from 'workbox-routing';

// This assumes /app-shell.html has been precached.
const handler = createHandlerBoundToURL('/app-shell.html');
const navigationRoute = new NavigationRoute(handler, {
  allowlist: [new RegExp('/blog/')],
  denylist: [new RegExp('/blog/restricted/')],
});
registerRoute(navigationRoute);

Es ist lediglich zu beachten, dass denylist gewinnt, wenn eine URL sowohl im allowlist- als auch im denylist-Element enthalten ist.

Standard-Handler festlegen

Wenn Sie einen „Handler“ für Anfragen angeben möchten, die mit keiner Route übereinstimmen, können Sie einen Standard-Handler festlegen.

import {setDefaultHandler} from 'workbox-routing';

setDefaultHandler(({url, event, params}) => {
  // ...
});

Catch-Handler einrichten

Wenn bei einer Ihrer Routen ein Fehler ausgegeben wird, können Sie mithilfe eines Catchall-Handlers die Erfassung und das Prinzip der Fehlertoleranz vornehmen.

import {setCatchHandler} from 'workbox-routing';

setCatchHandler(({url, event, params}) => {
  ...
});

Route für Nicht-GET-Anfragen definieren

Standardmäßig wird davon ausgegangen, dass alle Routen für GET-Anfragen vorgesehen sind.

Wenn Sie andere Anfragen weiterleiten möchten, z. B. eine POST-Anfrage, müssen Sie die Methode beim Registrieren der Route so definieren:

import {registerRoute} from 'workbox-routing';

registerRoute(matchCb, handlerCb, 'POST');
registerRoute(new RegExp('/api/.*\\.json'), handlerCb, 'POST');

Router-Logging

Anhand der Logs von workbox-routing sollten Sie den Ablauf einer Anfrage ermitteln können. Diese Logs zeigen, welche URLs mit Workbox verarbeitet werden.

Wenn Sie ausführlichere Informationen benötigen, können Sie die Logebene auf debug festlegen, um Logs für Anfragen aufzurufen, die nicht vom Router verarbeitet werden. Weitere Informationen zum Festlegen der Logebene finden Sie in unserem Leitfaden zur Fehlerbehebung.

Erweiterte Nutzung

Wenn Sie mehr Kontrolle darüber haben möchten, wann Anfragen an den Workbox Router gesendet werden, können Sie Ihre eigene Router-Instanz erstellen und deren Methode handleRequest() aufrufen, wenn Sie den Router zum Antworten auf eine Anfrage verwenden möchten.

import {Router} from 'workbox-routing';

const router = new Router();

self.addEventListener('fetch', event => {
  const {request} = event;
  const responsePromise = router.handleRequest({
    event,
    request,
  });
  if (responsePromise) {
    // Router found a route to handle the request.
    event.respondWith(responsePromise);
  } else {
    // No route was found to handle the request.
  }
});

Wenn Sie Router direkt verwenden, müssen Sie auch die Klasse Route oder eine der Erweiterungsklassen verwenden, um Routen zu registrieren.

import {Route, RegExpRoute, NavigationRoute, Router} from 'workbox-routing';

const router = new Router();
router.registerRoute(new Route(matchCb, handlerCb));
router.registerRoute(new RegExpRoute(new RegExp(...), handlerCb));
router.registerRoute(new NavigationRoute(handlerCb));

workbox-routing.registerRoute(
  capture: string|RegExp|RouteMatchCallback|Route,
  handler?: RouteHandler,
  method?: HTTPMethod,
)

workbox-routing.setCatchHandler(
  handler: RouteHandler,
)

workbox-routing.setDefaultHandler(
  handler: RouteHandler,
)