nuxt-app/packages/cache/readme.md

Cache System 使用文档

packages/cache 提供一个支持 Redis 主存储 + Memory 内存降级的通用 K-V 缓存系统。

安装

cache 包已作为 workspace 依赖安装，直接使用即可：

import { createCache } from 'cache'

快速开始

import { createCache } from 'cache'

// 初始化
const cache = createCache({
  redis: {
    host: '127.0.0.1',
    port: 6379,
  },
  defaultTtl: 300, // 默认 5 分钟
})

// 在 Nitro API 中使用
export default defineEventHandler(async (event) => {
  const key = 'users:list'

  // 尝试从缓存读取
  const cached = await cache.get(key)
  if (cached) return cached

  // 缓存未命中，从数据源获取
  const data = await fetchUsers()

  // 写入缓存
  await cache.set(key, data)

  return data
})

API

createCache(options)

创建 CacheManager 实例。

interface CacheFactoryOptions {
  redis?: RedisDriverOptions   // Redis 配置，省略则只用内存
  memory?: boolean            // 是否启用内存兜底，默认 true
  defaultTtl?: number         // 默认 TTL（秒），默认 0（永不过期）
}

interface RedisDriverOptions {
  host: string
  port: number
  password?: string
  db?: number
}

行为：

• redis 配置存在时，Redis 作为主存储（优先尝试）
• memory !== false 时，Memory 作为兜底（Redis 不可用时自动降级）
• 两者都不配置则抛出错误

CacheManager 实例方法

// 读取缓存，未命中返回 null
get<T = unknown>(key: string): Promise<T | null>

// 写入缓存
// ttl 单位为秒，0 表示永不过期
set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>

// 删除指定 key
del(key: string): Promise<void>

// 检查 key 是否存在
exists(key: string): Promise<boolean>

// 清空所有缓存（谨慎使用）
clear(): Promise<void>

降级策略

采用手动显式降级：按驱动数组顺序尝试，返回第一个成功结果。

RedisDriver (优先)
  ↓ 失败时
MemoryDriver (兜底)

• get / exists：遍历 drivers，返回第一个成功结果
• set / del / clear：并发写入/删除所有 drivers（保证各层数据一致）
• 单个 driver 失败时 warn 并继续，不影响整体操作

使用场景

场景一：纯内存缓存（开发/无 Redis 环境）

const cache = createCache({
  defaultTtl: 60,
})

场景二：Redis + 内存降级（生产环境）

const cache = createCache({
  redis: {
    host: process.env.REDIS_HOST!,
    port: Number(process.env.REDIS_PORT ?? 6379),
    password: process.env.REDIS_PASSWORD,
    db: Number(process.env.REDIS_DB ?? 0),
  },
  defaultTtl: 300,
})

场景三：禁用内存兜底（Redis 专用）

const cache = createCache({
  redis: { host: '127.0.0.1', port: 6379 },
  memory: false,
})

数据结构

所有值以 JSON 序列化存储到 Redis：

await cache.set('user:1', { id: 1, name: 'Alice' })
// Redis: SET 'user:1' '{"id":1,"name":"Alice"}' EX 300

注意事项

• TTL 单位是秒，Redis EX 参数单位也是秒
• clear() 在 Redis 上执行 FLUSHDB，会清空整个数据库，请确认 namespace 隔离
• MemoryDriver 使用进程内存，重启进程后缓存丢失
• 不支持存储 undefined、Symbol 或含循环引用的对象（JSON 序列化限制）