Cache ミドルウェア

Cache ミドルウェアは、Web 標準の Cache API を使用します。

現在、Cache ミドルウェアは、カスタムドメインを使う Cloudflare Workers プロジェクトと、Deno 1.26+ を使う Deno プロジェクトをサポートします。Deno Deploy でも利用できます。

Cloudflare Workers は Cache-Control ヘッダーに従い、キャッシュしたレスポンスを返します。詳細は Cloudflare のキャッシュドキュメントを参照してください。Deno はヘッダーに従わないため、キャッシュを更新する必要があれば独自の仕組みを実装してください。

各プラットフォームの手順は、以下の使い方を参照してください。

インポート

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

使い方

Cloudflare Workers

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

Deno

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

QUERY リクエストのキャッシュ

Cache ミドルウェアは QUERY リクエストのレスポンスもキャッシュします。RFC 10008 の要件に従い、QUERY のキャッシュキーにはリクエスト内容とその表現メタデータのダイジェストを含めます。そのため、ボディが異なるリクエストは別々にキャッシュされます。

ボディが maxQueryBodySize（デフォルト 64 KiB）を超える QUERY リクエストは、キャッシュを使用しません。

情報

これをサポートするため、キャッシュエントリーはリクエスト URL 自体ではなく、/.hono/cache?__hono_cache_key=... 形式の内部キーに保存されます。Cache API で直接エントリーを削除している場合（元のリクエスト URL で caches.delete() を呼ぶ場合など）は、そのロジックを更新する必要があります。GET を含むすべてのメソッドに適用されます。

オプション

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

キャッシュの名前。異なる識別子を持つ複数のキャッシュを保存できます。

optional wait: boolean

cache.put 関数の Promise が解決するまで Hono が待ってからリクエスト処理を続けるかを示す真偽値です。Deno 環境では true が必須です。デフォルトは false です。

optional cacheControl: string

Cache-Control ヘッダーのディレクティブ文字列です。詳しくは MDN ドキュメントを参照してください。このオプションがなければ、リクエストに Cache-Control ヘッダーは追加されません。

optional vary: string | string[]

レスポンスの Vary ヘッダーを設定します。元のレスポンスに Vary があれば、重複を除いて値を統合します。* に設定するとエラーになります。Vary ヘッダーとキャッシュ戦略への影響については、MDN ドキュメントを参照してください。

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

cacheName ストアの各リクエスト用にキーを生成します。リクエストパラメーターやコンテキストパラメーターに基づいてデータをキャッシュできます。デフォルトは c.req.url です。QUERY リクエストのキーには、内容とその表現メタデータのダイジェストも含まれます。

optional maxQueryBodySize: number

キャッシュ可能な QUERY リクエストボディの最大サイズ（バイト単位）です。これを超える QUERY リクエストはキャッシュを使用しません。デフォルトは 65536（64 KiB）です。

optional cacheableStatusCodes: number[]

キャッシュするステータスコードの配列です。デフォルトは [200] です。このオプションで、特定のステータスコードのレスポンスをキャッシュできます。

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

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

グローバルスコープで Cache API が利用できない場合や、QUERY キャッシュで Web Crypto が使えない場合の動作を制御するコールバック関数または false です。コールバックには理由が渡されます。デフォルトでは 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,
  })
)