workbox-cacheable-response

כששומרים נכסים במטמון בזמן הריצה, אין כלל אחד שמתאים לכולם שקובע אם תגובה נתונה היא 'חוקית', ואפשר לשמור אותה ולהשתמש בה שוב.

המודול workbox-cacheable-response מספק דרך סטנדרטית לקבוע אם תגובה צריכה להישמר במטמון על סמך קוד הסטטוס המספרי שלה, נוכחות כותרת עם ערך ספציפי או שילוב של שניהם.

שמירה במטמון על סמך קודי סטטוס

אפשר להגדיר אסטרטגיית תיבת עבודה כדי שקבוצה של קודי סטטוס תתאים לשמירה במטמון על ידי הוספת מופע CacheableResponsePlugin לפרמטר plugins של האסטרטגיה:

import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';
import {CacheableResponsePlugin} from 'workbox-cacheable-response';

registerRoute(
  ({url}) =>
    url.origin === 'https://third-party.example.com' &&
    url.pathname.startsWith('/images/'),
  new CacheFirst({
    cacheName: 'image-cache',
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200],
      }),
    ],
  })
);

ההגדרה הזו מורה ל-Workbox שכשמעבדים תגובות לבקשות מול https://third-party.example.com/images/, צריך לשמור במטמון את כל הבקשות עם קוד הסטטוס 0 או 200.

שמירה במטמון לפי כותרות

אפשר להגדיר אסטרטגיית תיבת עבודה כדי לבדוק אם יש ערכי כותרת ספציפיים כקריטריונים להוספה למטמון, על ידי הגדרת האובייקט headers כשיוצרים את הפלאגין:

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

registerRoute(
  ({url}) => url.pathname.startsWith('/path/to/api/'),
  new StaleWhileRevalidate({
    cacheName: 'api-cache',
    plugins: [
      new CacheableResponsePlugin({
        headers: {
          'X-Is-Cacheable': 'true',
        },
      }),
    ],
  })
);

כשמעבדים תגובות לכתובות URL של בקשות שמכילות /path/to/api/, חשוב לבדוק את הכותרת בשם X-Is-Cacheable (שתתווסף לתגובה על ידי השרת). אם הכותרת הזו קיימת, ואם היא מוגדרת לערך 'true', אפשר לשמור את התגובה במטמון.

אם צוינו כמה כותרות, רק אחת מהכותרות צריכה להתאים לערכים המשויכים.

שמירה במטמון לפי כותרות וקודי סטטוס

אפשר לשלב גם סטטוס וגם הגדרת כותרת. שני התנאים חייבים להתקיים כדי שהתגובה תיחשב כניתנת לשמירה. במילים אחרות, התגובה צריכה להכיל אחד מקודי הסטטוס שהוגדרו, וגם לפחות אחת מהכותרות שצוינו.

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

registerRoute(
  ({url}) => url.pathname.startsWith('/path/to/api/'),
  new StaleWhileRevalidate({
    cacheName: 'api-cache',
    plugins: [
      new CacheableResponsePlugin({
        statuses: [200, 404],
        headers: {
          'X-Is-Cacheable': 'true',
        },
      }),
    ],
  })
);

מהן ברירות המחדל?

אם משתמשים באחת מהאסטרטגיות המובנות של Workbox בלי להגדיר cacheableResponse.CacheableResponsePlugin באופן מפורש, הקריטריונים הבאים של ברירת המחדל משמשים כדי לקבוע אם תגובה שמתקבלת מהרשת תישמר במטמון:

  • staleזמןRevalidate ו-NetworkFirst: תשובות עם סטטוס של 0 (כלומר תגובות אטומות) או 200 נחשבות כתגובות שניתן לשמור במטמון.
  • cacheFirst: תגובות עם סטטוס 200 נחשבות כניתנות לשמירה.

כברירת מחדל, כותרות התגובות לא משמשות לקביעת יכולת השמירה במטמון.

למה יש ברירות מחדל שונות?

הגדרות ברירת המחדל משתנות בהתאם לשאלה האם תשובות עם סטטוס של 0 (כלומר תגובות אטומות) יישמרו במטמון. בגלל אופי "התיבה השחורה" של תגובות אטומות, ל-Service Worker אין אפשרות לדעת אם התגובה חוקית או אם היא משקפת שגיאה שמוחזרת משרת חוצה-מקורות.

באסטרטגיות שכוללות כמה אמצעים לעדכון התגובה שנשמרה במטמון, כמו stalewhileRevalidate ו-networkFirst, יש סיכון נמוך לשמירה של תגובת שגיאה זמנית, כי בפעם הבאה שהמטמון יתעדכן, ייעשה שימוש בתגובה תקינה ומוצלחת.

באסטרטגיות שכוללות שמירה של התגובה הראשונה שהתקבלה במטמון ושימוש חוזר בתגובה ששמורה במטמון ללא הגבלת זמן, ההשלכות של שגיאה זמנית בשמירה במטמון ובשימוש חוזר הן חמורות יותר. על מנת לדאוג לכך כברירת מחדל, התכונה 'cacheFirst' תסרב לשמור תשובה אלא אם קוד הסטטוס שלה הוא 200.

שימוש מתקדם

אם רוצים להשתמש באותה לוגיקה של שמירה במטמון מחוץ לאסטרטגיית Workbox, אפשר להשתמש ישירות בכיתה CacheableResponse.

import {CacheableResponse} from 'workbox-cacheable-response';

const cacheable = new CacheableResponse({
  statuses: [0, 200],
  headers: {
    'X-Is-Cacheable': 'true',
  },
});

const response = await fetch('/path/to/api');

if (cacheable.isResponseCacheable(response)) {
  const cache = await caches.open('api-cache');
  cache.put(response.url, response);
} else {
  // Do something when the response can't be cached.
}

סוגים

CacheableResponse

המחלקה הזו מאפשרת להגדיר כללים שקובעים אילו קודי סטטוס ו/או כותרות צריכים להיכלל כדי ש-Response ייחשב כניתן לשמירה במטמון.

תכונות

  • Constructor

    void

    כדי ליצור מכונה חדשה של CacheableResponse, צריך לספק לפחות אחד מהמאפיינים config.

    אם מציינים גם statuses וגם headers, שני התנאים חייבים להתקיים כדי ש-Response ייחשב ניתן לשמירה במטמון.

    הפונקציה constructor נראית כך:

    (config?: CacheableResponseOptions) => {...}

  • isResponseCacheable

    void

    בודקת תגובה כדי לראות אם היא ניתנת לשמירה או לא, על סמך ההגדרות של האובייקט.

    הפונקציה isResponseCacheable נראית כך:

    (response: Response) => {...}

    • תשובה

      תשובה

      התגובה שאפשרות השמירה שלה נבדקת במטמון.

    • החזרות

      boolean

      true אם ניתן לשמור את Response במטמון וגם false אם לא.

CacheableResponseOptions

תכונות

  • headers

    אובייקט אופציונלי

  • סטטוסים

    number[] אופציונלי

CacheableResponsePlugin

מחלקה שמטמיעה את הקריאה החוזרת של מחזור החיים של cacheWillUpdate. כך קל יותר להוסיף בדיקות של אפשרות שמירה במטמון לבקשות שנשלחות באמצעות האסטרטגיות המובנות של Workbox.

תכונות

  • Constructor

    void

    כדי ליצור מכונת CacheableResponsePlugin חדשה, צריך לספק לפחות אחד ממאפייני config.

    אם מציינים גם statuses וגם headers, שני התנאים חייבים להתקיים כדי ש-Response ייחשב ניתן לשמירה במטמון.

    הפונקציה constructor נראית כך:

    (config: CacheableResponseOptions) => {...}