برمجية وسيطة للتخزين المؤقت

يستخدم وسيط التخزين المؤقت (Cache) Cache API.

يدعم وسيط Cache حاليًا مشاريع Cloudflare Workers التي تستخدم نطاقات مخصصة، ومشاريع Deno التي تستخدم Deno 1.26+. متاح أيضًا مع Deno Deploy.

يحترم Cloudflare Workers الـ Cache-Control الترويسة (header) وإرجاع الاستجابات المخزَّنة مؤقتاً. للتفاصيل، راجع التخزين المؤقت في وثائق Cloudflare. لا يحترم Deno الترويسات، لذا إذا كنت بحاجة إلى تحديث ذاكرة التخزين المؤقت (cache)، ستحتاج إلى تنفيذ آلية خاصة بك.

انظر الاستخدام أدناه للحصول على تعليمات لكل منصة.

Import

import { Hono } from 'hono'
import { cache } from 'hono/cache'

الاستخدام

app.get(
  '*',
  cache({
    cacheName: 'my-app',
    cacheControl: 'max-age=3600',
  })
)

// Must use `wait: true` for the Deno runtime
app.get(
  '*',
  cache({
    cacheName: 'my-app',
    cacheControl: 'max-age=3600',
    wait: true,
  })
)

تخزين طلبات QUERY مؤقتًا

يخزّن وسيط التخزين المؤقت أيضًا الاستجابات لـ QUERY الطلبات. وفقًا لما تتطلبه RFC 10008، يتضمن مفتاح التخزين المؤقت لطلب QUERY ملخصًا (digest) لمحتوى الطلب وبياناته الوصفية (metadata) الخاصة بالتمثيل، لذا تُخزن الطلبات ذات النصوص المختلفة مؤقتًا بشكل منفصل.

طلبات QUERY بجسم أكبر من maxQueryBodySize (64 KiB افتراضيًا) تتجاوز الذاكرة المؤقتة (cache).

لدعم ذلك، تُخزَّن الإدخالات المخزنة مؤقتًا (cached entries) تحت مفتاح داخلي بالصيغة /.hono/cache?__hono_cache_key=... بدلًا من عنوان URL للطلب نفسه. إذا قمت بمسح إدخالات ذاكرة التخزين المؤقت مباشرة عبر Cache API — على سبيل المثال، استدعاء caches.delete() مع عنوان URL الأصلي للطلب — ستحتاج إلى تحديث هذا المنطق. ينطبق هذا على جميع الأساليب، بما في ذلك GET.

الخيارات

cacheName: string | (c: Context) => string | Promise<string>

اسم ذاكرة التخزين المؤقت (cache). يمكن استخدامه لتخزين عدة مخابئ بمعرفات مختلفة.

wait: boolean

قيمة منطقية (boolean) تشير إلى ما إذا كان ينبغي لـ Hono انتظار Promise الخاص بـ cache.put الدالة لإكمال التنفيذ قبل المتابعة مع الطلب. مطلوب أن يكون true لبيئة Deno. الافتراضي هو false.

cacheControl: string

سلسلة من التوجيهات لـ Cache-Control الترويسة. راجع وثائق MDN لمزيد من المعلومات. عند عدم توفير هذا الخيار، لا Cache-Control تُضاف الترويسة إلى الطلبات.

vary: string | string[]

يضبط Vary في الاستجابة. إذا كان رأس الاستجابة الأصلي يحتوي بالفعل على Vary الرأس (header)، يتم دمج القيم مع إزالة أي قيم مكررة. وضبط هذا على * سيؤدي إلى خطأ. لمزيد من التفاصيل حول ترويسة Vary وتأثيراتها على استراتيجيات التخزين المؤقت، راجع وثائق MDN.

keyGenerator: (c: Context) => string | Promise<string>

يولّد مفاتيح لكل طلب في cacheName مخزن. يمكن استخدامه لتخزين البيانات مؤقتًا بناءً على معاملات الطلب أو معاملات السياق. الافتراضي هو c.req.url. بالنسبة لطلبات QUERY، يتضمن المفتاح أيضًا ملخصًا (digest) لمحتوى الطلب وبياناته الوصفية (metadata) الخاصة بالتمثيل.

maxQueryBodySize: number

الحد الأقصى لحجم نص طلب QUERY بالبايت الذي يمكن تخزينه مؤقتًا. طلبات QUERY ذات النص الأكبر تتجاوز ذاكرة التخزين المؤقت. الافتراضي هو 65536 (64 KiB).

cacheableStatusCodes: number[]

مصفوفة برموز الحالة (status codes) التي ينبغي تخزينها مؤقتاً. الافتراضي هو [200]. استخدم هذا الخيار لتخزين الاستجابات ذات رموز الحالة (status codes) المحددة مؤقتًا في ذاكرة التخزين المؤقت (cache).

app.get(
  '*',
  cache({
    cacheName: 'my-app',
    cacheControl: 'max-age=3600',
    cacheableStatusCodes: [200, 404, 412],
  })
)

onCacheNotAvailable: ((reason: string) => void | Promise<void>) | false

دالة استدعاء رجعي أو false الذي يتحكم في السلوك عندما لا تكون Cache API متاحة في النطاق العام (global scope)، أو عندما لا يمكن لتخزين QUERY المؤقت استخدام Web Crypto. تُستدعى الدالة مع السبب. افتراضيًا، يُسجل السبب باستخدام console.log. يمكنك تقديم دالة مخصصة لتخصيص السلوك، أو ضبطها على false لكتم السجل بالكامل.

// Custom logging
app.use(
  cache({
    cacheName: 'my-app-v1',
    onCacheNotAvailable: () => {
      console.log('Custom log: Cache API is not available.')
    },
  })
)

// Suppress logging
app.use(
  cache({
    cacheName: 'my-app-v1',
    onCacheNotAvailable: false,
  })
)