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 请求会绕过缓存。

说明

为支持此功能，缓存条目存储在 /.hono/cache?__hono_cache_key=... 形式的内部键下，而不是直接使用请求 URL。如果通过 Cache API 直接清除缓存条目（例如用原请求 URL 调用 caches.delete()），需要更新相应逻辑。这适用于包括 GET 在内的所有方法。

选项

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

缓存名称。可用于存储具有不同标识的多个缓存。

optional wait: boolean

布尔值，指定 Hono 是否等待 cache.put 函数返回的 Promise 完成，再继续处理请求。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

回调函数或 false，用于控制全局作用域中 Cache API 不可用，或 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,
  })
)