# 可降级缓存系统设计

**日期:** 2026-05-22
**状态:** approved

## 1. 概述

设计一个 Server-only 的通用 K-V 缓存系统 `packages/cache`，支持 Redis 主存储 + Memory 内存兜底。当 Redis 不可用时，自动降级到内存缓存，对调用方透明。

## 2. 架构

```
packages/cache/
├── package.json
├── index.ts              ← 导出工厂函数和类型
└── lib/
    ├── types.ts          ← 核心类型定义
    ├── managers/
    │   └── cache-manager.ts   ← CacheManager 实现
    └── drivers/
        ├── base.ts             ← Driver 基类 / 接口
        ├── memory-driver.ts    ← 内存驱动
        └── redis-driver.ts     ← Redis 驱动（ioredis）
```

### 设计原则

- 分层适配器：调用方只跟 `CacheManager` 交互，不感知底层存储
- 手动显式降级：按 `drivers` 数组顺序尝试，返回第一个成功结果
- 扩展性：新增驱动（如 `cloudflare-kv-driver`）只需实现 `CacheDriver` 接口

## 3. 核心类型

```typescript
// lib/types.ts
export interface CacheOptions {
  ttl?: number          // 默认 TTL（秒），0 = 不过期
  namespace?: string    // key 前缀隔离（未来扩展）
}

export interface CacheEntry<T = unknown> {
  value: T
  expiresAt: number | null // Unix ms，null = 永不过期
}

export interface CacheDriver {
  name: string
  get<T = unknown>(key: string): Promise<T | null>
  set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>
  del(key: string): Promise<void>
  exists(key: string): Promise<boolean>
  clear(): Promise<void>
}

export interface CacheManagerOptions {
  drivers: CacheDriver[]
  defaultTtl?: number
}
```

## 4. CacheManager

**文件:** `lib/managers/cache-manager.ts`

```typescript
export class CacheManager {
  private drivers: CacheDriver[]
  private defaultTtl: number

  constructor(options: CacheManagerOptions)

  async get<T = unknown>(key: string): Promise<T | null>
  async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>
  async del(key: string): Promise<void>
  async exists(key: string): Promise<boolean>
  async clear(): Promise<void>

  withPrefix(ns: string): CacheManager
}
```

**降级逻辑（get）：** 遍历 `drivers`，返回第一个成功结果，全部失败返回 `null`。

**一致性逻辑（set/del/exists/clear）：** 遍历所有 driver 并发写入，确保降级后各层数据一致。

## 5. MemoryDriver

**文件:** `lib/drivers/memory-driver.ts`

- 用 `Map<string, { value, expiresAt }>` 存储
- TTL = 0 不设置过期时间
- 过期检查在 `get` 时懒清理（检查 `expiresAt` 是否已到）
- `clear()` 清空整个 Map

## 6. RedisDriver

**文件:** `lib/drivers/redis-driver.ts`

- 使用 `ioredis` 客户端
- value 序列化为 `JSON.stringify` 存储
- TTL = 0 时使用 `persist`（不设过期）
- `clear()` 使用 `FLUSHDB` 清空当前数据库（假设 prod 使用独立 db）
- 需支持 disconnect 关闭连接

**RedisOptions:**
```typescript
interface RedisOptions {
  host: string
  port: number
  password?: string
  db?: number
}
```

## 7. 工厂函数

**文件:** `index.ts`

```typescript
interface CacheFactoryOptions {
  redis?: {
    host: string
    port: number
    password?: string
    db?: number
  }
  memory?: boolean      // 是否启用内存兜底，默认 true
  defaultTtl?: number   // 默认 TTL（秒）
}

function createCache(options: CacheFactoryOptions): CacheManager
```

**行为：**
- 如果指定了 `redis`，则将其作为主驱动加入 drivers 数组首位
- 如果 `memory !== false`，则将 MemoryDriver 加入 drivers 数组末位
- 如果既没有 `redis` 也没有内存（`memory: false`），抛出错误

## 8. 使用方式

```typescript
// 初始化（在 Nitro 插件或 server/utils 中
const cache = createCache({
  redis: { host: '127.0.0.1', port: 6379 },
  defaultTtl: 300,
})

// 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
})
```

## 9. 错误处理

- `get` 操作：单个 driver 失败时 warn 并尝试下一个；全部失败返回 `null`
- `set/del/exists/clear` 操作：单个 driver 失败时 warn 但不中断（因为是并发写）
- Redis 连接失败（如网络不可达）：触发降级，不影响服务启动

## 10. 依赖

```json
{
  "ioredis": "^5.x"
}
```

内存驱动无外部依赖。