pre-memorizzazione nella cache della casella di lavoro

Una caratteristica dei service worker è la possibilità di salvare un insieme di file nella cache durante l'installazione del service worker. Questa situazione viene spesso denominata "precaching", poiché i contenuti vengono memorizzati nella cache prima del service worker utilizzato.

Il motivo principale di questa scelta è che gli sviluppatori hanno il controllo sulla cache, il che significa che possono determinare quando e per quanto tempo un file viene memorizzato nella cache e per pubblicarlo nel browser senza accedere alla rete, il che significa che possono essere utilizzati per creare app web che funzionano offline.

Workbox elimina molto il lavoro pesante di pre-memorizzazione nella cache semplificando l'API e garantendo che gli asset vengano scaricati in modo efficiente.

Come funziona la pre-memorizzazione nella cache di lavoro

Quando un'app web viene caricata per la prima volta, workbox-precaching controlla tutti gli asset che vuoi scaricare, rimuove eventuali duplicati e collega gli eventi dei service worker pertinenti per scaricare e archiviare gli asset. Gli URL che già includono informazioni sul controllo delle versioni (ad esempio, un hash dei contenuti) vengono utilizzati come chiavi cache senza ulteriori modifiche. Gli URL che non includono informazioni sul controllo delle versioni hanno un parametro di query URL aggiuntivo aggiunto alla chiave cache che rappresenta un hash dei contenuti generato da Workbox al momento della creazione.

workbox-precaching esegue queste operazioni durante l'evento install del service worker.

Quando un utente accede di nuovo alla tua applicazione web in un secondo momento e hai un nuovo service worker con diversi asset prememorizzati nella cache, workbox-precaching esaminerà il nuovo elenco e determinerà quali asset sono completamente nuovi e quali esistenti devono essere aggiornati, in base alla relativa revisione. Eventuali nuovi asset o revisioni in fase di aggiornamento verranno aggiunti alla cache durante l'evento install del nuovo service worker.

Questo nuovo service worker non verrà utilizzato per rispondere alle richieste finché non verrà attivato il relativo evento activate. È nell'evento activate che workbox-precaching controlla se sono presenti asset memorizzati nella cache che non sono più presenti nell'elenco degli URL correnti e li rimuove dalla cache.

workbox-precaching eseguirà questi passaggi ogni volta che il service worker viene installato e attivato, assicurando che l'utente disponga degli asset più recenti e scaricando solo i file che sono stati modificati.

Pubblicazione di risposte pre-memorizzate nella cache

La chiamata a precacheAndRoute() o addRoute() crea una route che corrisponde alle richieste di URL pre-memorizzati nella cache.

La strategia di risposta utilizzata in questa route è cache-first: verrà utilizzata la risposta prememorizzata nella cache, a meno che non sia presente una risposta memorizzata nella cache (a causa di un errore imprevisto), nel qual caso verrà utilizzata una risposta di rete.

L'ordine in cui chiami precacheAndRoute() o addRoute() è importante. Normalmente consigliamo di chiamarlo all'inizio del file del service worker, prima di registrare eventuali route aggiuntive con registerRoute(). Se prima hai chiamato registerRoute() e questa route corrisponde a una richiesta in entrata, per rispondere verrà utilizzata qualsiasi strategia definita nella route aggiuntiva al posto della strategia cache-first utilizzata da workbox-precaching.

Spiegazione dell'elenco di pre-cache

workbox-precaching prevede un array di oggetti con una proprietà url e revision. Questo array viene a volte indicato come manifest precache:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([
  {url: '/index.html', revision: '383676'},
  {url: '/styles/app.0c9a31.css', revision: null},
  {url: '/scripts/app.0d5770.js', revision: null},
  // ... other entries ...
]);

Questo elenco fa riferimento a un insieme di URL, ciascuno con la propria informazione sul "revisione".

Per il secondo e il terzo oggetto dell'esempio precedente, la proprietà revision è impostata su null. Questo perché le informazioni sulla revisione si trovano nell'URL stesso, che è in genere una best practice per gli asset statici.

Il primo oggetto (/index.html) imposta in modo esplicito una proprietà di revisione, ovvero un hash dei contenuti del file generato automaticamente. A differenza delle risorse JavaScript e CSS, in genere i file HTML non possono includere informazioni di revisione negli URL; in caso contrario, i link a questi file sul web non funzionarerebbero ogni volta che i contenuti della pagina venivano modificati.

Passando una proprietà della revisione a precacheAndRoute(), Workbox può sapere quando il file è stato modificato e aggiornarlo di conseguenza.

Workbox include strumenti che consentono di generare questo elenco:

• workbox-build: questo è un pacchetto di nodi che può essere utilizzato in un'attività gulp o come script di esecuzione npm.
• workbox-webpack-plugin: gli utenti del webpack possono utilizzare questo plug-in.
• workbox-cli: la nostra interfaccia a riga di comando può essere utilizzata anche per generare l'elenco di asset e aggiungerli al service worker.

Richieste in entrata di file prememorizzati nella cache

Una cosa che workbox-precaching farà subito è manipolare le richieste di rete in entrata per provare ad associare i file pre-memorizzati nella cache. Ciò è conforme alle pratiche comuni sul web.

Ad esempio, una richiesta per / in genere può essere soddisfatta dal file all'indirizzo /index.html.

Di seguito è riportato l'elenco delle manipolazioni eseguite per impostazione predefinita da workbox-precaching e viene spiegato come puoi alterare tale comportamento.

Ignora parametri URL

Le richieste con parametri di ricerca possono essere modificate per rimuovere valori specifici o tutti i valori.

Per impostazione predefinita, i parametri di ricerca che iniziano con utm_ o corrispondono esattamente a fbclid vengono rimossi, il che significa che una richiesta per /about.html?utm_campaign=abcd verrà soddisfatta con una voce prememorizzata per /about.html.

Puoi ignorare un insieme diverso di parametri di ricerca utilizzando ignoreURLParametersMatching:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    // Ignore all URL parameters.
    ignoreURLParametersMatching: [/.*/],
  }
);

Indice directory

Per impostazione predefinita, le richieste che terminano con / verranno abbinate a voci con un index.html aggiunto alla fine. Ciò significa che una richiesta in entrata per / può essere gestita automaticamente con la voce prememorizzata nella cache /index.html.

Puoi modificarla in qualcos'altro o disattivarla completamente impostando directoryIndex:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    directoryIndex: null,
  }
);

Pulisci URL

Se una richiesta non corrisponde alla pre-cache, aggiungeremo .html alla fine per supportare URL "puliti" (ovvero URL "pretty"). Ciò significa che una richiesta come /about verrà gestita dalla voce prememorizzata nella cache per /about.html.

Puoi disattivare questo comportamento impostando cleanUrls:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([{url: '/about.html', revision: 'b79cd4'}], {
  cleanUrls: false,
});

Manipolazioni personalizzate

Se vuoi definire corrispondenze personalizzate dalle richieste in arrivo agli asset pre-memorizzati nella cache, puoi farlo utilizzando l'opzione urlManipulation. Si tratta di un callback che restituisce un array di possibili corrispondenze.

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    urlManipulation: ({url}) => {
      // Your logic goes here...
      return [alteredUrlOption1, alteredUrlOption2];
    },
  }
);

Utilizzo avanzato

Utilizzo diretto di PrecacheController

Per impostazione predefinita, workbox-precaching configura i listener install e activate per te. Per gli sviluppatori che hanno familiarità con i service worker, questa operazione potrebbe non essere auspicabile se si ha bisogno di un maggiore controllo.

Anziché utilizzare l'esportazione predefinita, puoi utilizzare PrecacheController direttamente per aggiungere elementi alla precache, determinare quando vengono installati questi asset e quando deve essere eseguita la pulizia.

import {PrecacheController} from 'workbox-precaching';

const precacheController = new PrecacheController();
precacheController.addToCacheList([
  {url: '/styles/example-1.abcd.css', revision: null},
  {url: '/styles/example-2.1234.css', revision: null},
  {url: '/scripts/example-1.abcd.js', revision: null},
  {url: '/scripts/example-2.1234.js', revision: null},
]);

precacheController.addToCacheList([{
  url: '/index.html',
  revision: 'abcd',
}, {
  url: '/about.html',
  revision: '1234',
}]);

self.addEventListener('install', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.install(event));
});

self.addEventListener('activate', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.activate(event));
});

self.addEventListener('fetch', (event) => {
  const cacheKey = precacheController.getCacheKeyForURL(event.request.url);
  event.respondWith(caches.match(cacheKey).then(...));
});

lettura diretta degli asset pre-memorizzati nella cache

A volte potrebbe essere necessario leggere direttamente un asset pre-memorizzato nella cache, al di fuori del contesto del routing che workbox-precaching può eseguire automaticamente. Ad esempio, potresti voler memorizzare nella cache i modelli HTML parziali che devono essere recuperati e utilizzati durante la creazione di una risposta completa.

In generale, puoi utilizzare l'API Cache Storage per ottenere gli oggetti Response pre-memorizzati nella cache, ma c'è un piccolo aspetto: la chiave cache dell'URL che deve essere utilizzata per la chiamata a cache.match() potrebbe contenere un parametro di controllo delle versioni che workbox-precaching crea e gestisce automaticamente.

Per ottenere la chiave cache corretta, puoi chiamare getCacheKeyForURL(), trasmettere l'URL originale, quindi utilizzare il risultato per eseguire cache.match() nella cache appropriata.

import {cacheNames} from 'workbox-core';
import {getCacheKeyForURL} from 'workbox-precaching';

const cache = await caches.open(cacheNames.precache);
const response = await cache.match(getCacheKeyForURL('/precached-file.html'));

In alternativa, se tutto ciò che ti serve è l'oggetto Response prememorizzato nella cache, puoi chiamare matchPrecache(), che utilizzerà automaticamente la chiave cache corretta e cercherà nella cache corretta:

import {matchPrecache} from 'workbox-precaching';

const response = await matchPrecache('/precached-file.html');

Pulisci vecchie pre-cache

La maggior parte delle release di Workbox mantiene lo stesso formato per l'archiviazione dei dati pre-memorizzati nella cache e, in genere, le pre-cache create da versioni precedenti di Workbox possono essere utilizzate così come sono dalle release più recenti. Raramente, però, si verifica un cambiamento che provoca un errore nell'archiviazione della pre-cache che richiede agli utenti esistenti di scaricare di nuovo tutti i contenuti e che rende obsoleti i dati precedentemente pre-memorizzati nella cache. (Un tale cambiamento è avvenuto tra le release Workbox v3 e v4.)

Questi dati obsoleti non dovrebbero interferire con le normali operazioni, ma contribuiscono all'utilizzo complessivo della quota di spazio di archiviazione e potrebbe essere più facile per gli utenti eliminarli in modo esplicito. A questo scopo, aggiungi cleanupOutdatedCaches() al service worker o imposta cleanupOutdatedCaches: true se utilizzi uno degli strumenti di creazione di Workbox per generare il service worker.

Utilizzo dell'integrità delle sottorisorse

Alcuni sviluppatori potrebbero richiedere le garanzie aggiuntive offerte dall'applicazione forzata dell'integrità delle sottorisorse durante il recupero degli URL pre-memorizzati nella cache dalla rete.

Puoi aggiungere un'ulteriore proprietà facoltativa denominata integrity a qualsiasi voce del manifest di pre-cache. Se fornito, verrà utilizzato come valore integrity durante la creazione del valore Request utilizzato per compilare la cache. Se viene rilevata una mancata corrispondenza, il processo di prememorizzazione nella cache non andrà a buon fine.

La determinazione delle voci manifest di pre-cache che devono avere proprietà integrity e la determinazione dei valori appropriati da utilizzare non rientrano nell'ambito degli strumenti di creazione di Workbox. Gli sviluppatori che vogliono attivare questa funzionalità devono modificare il manifest precache generato da Workbox per aggiungere autonomamente le informazioni appropriate. L'opzione manifestTransform nella configurazione degli strumenti di creazione di Workbox può aiutarti a:

const ssri = require('ssri');

const integrityManifestTransform = (originalManifest, compilation) => {
  const warnings = [];
  const manifest = originalManifest.map(entry => {
    // If some criteria match:
    if (entry.url.startsWith('...')) {
      // This has to be a synchronous function call, for example:
      // compilation will be set when using workbox-webpack-plugin.
      // When using workbox-build directly, you can read the file's
      // contents from disk using, e.g., the fs module.
      const asset = compilation.getAsset(entry.url);
      entry.integrity = ssri.fromData(asset.source.source()).toString();

      // Push a message to warnings if needed.
    }
    return entry;
  });

  return {warnings, manifest};
};

// Then add manifestTransform: [integrityManifestTransform]
// to your Workbox build configuration.

workbox-precaching.urlManipulation(
  { url }: object,
)

workbox-precaching.addPlugins(
  plugins: WorkboxPlugin[],
)

workbox-precaching.addRoute(
  options?: PrecacheRouteOptions,
)

workbox-precaching.cleanupOutdatedCaches()

workbox-precaching.createHandlerBoundToURL(
  url: string,
)

workbox-precaching.getCacheKeyForURL(
  url: string,
)

workbox-precaching.matchPrecache(
  request: string | Request,
)

workbox-precaching.precache(
  entries: (string | PrecacheEntry)[],
)

workbox-precaching.precacheAndRoute(
  entries: (string | PrecacheEntry)[],
  options?: PrecacheRouteOptions,
)