chanjs 2.7.3 → 2.7.5

package/doc/Cache.md

@@ -1,160 +1,333 @@
-# Cache 工具类文档
+# Cache 缓存工具
+
 ## 概述
-`Cache` 是一个基于内存实现的 LRU（最近最少使用）缓存类，支持 TTL（生存时间）过期策略和自动过期清理机制。该类通过两个 `Map` 分别存储缓存数据和访问顺序，既保证了缓存的快速存取，又能实现 LRU 淘汰策略，适用于需要临时缓存数据且对内存使用有控制需求的场景。
 
-## 安装与引入
-从 `chanjs/helper` 模块中引入 `Cache` 类和默认实例：
-```javascript
-import { Cache } from 'chanjs/helper';
-// 或引入预创建的默认缓存实例
-import { cache } from 'chanjs/helper';
-```
+`Cache` 是基于单 Map 实现的 LRU + 惰性 TTL 过期清理缓存类，对齐 Redis incr 行为，专用于限流场景的内存存储。
+
+## 特性
 
-## 类构造器
-### `constructor(options = {})`
-创建缓存实例，初始化最大容量和默认过期时间。
+- **LRU 淘汰**：访问刷新 LRU 顺序，容量超限时自动淘汰最久未使用的条目
+- **惰性 TTL**：自增不续期，批量惰性清理过期条目
+- **容量淘汰**：达到最大容量时自动 LRU 淘汰
+- **高性能**：10w 容量，定时批量清理避免阻塞事件循环
 
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| options.maxSize | number | 1000 | 缓存最大条目数，达到该数量时会自动淘汰最久未使用的条目 |
-| options.defaultTTL | number | 300000（5分钟） | 默认过期时间（毫秒），未指定 TTL 时使用该值 |
+## 引入方式
 
-**示例**：
 ```javascript
-// 创建自定义配置的缓存实例
-const customCache = new Cache({
-  maxSize: 500,    // 最大缓存500条
-  defaultTTL: 60000 // 默认1分钟过期
-});
+import { cache } from 'chanjs';
 
-// 使用默认配置的缓存实例（maxSize=1000，defaultTTL=5分钟）
-const defaultCache = new Cache();
+// 或创建自定义实例
+import Cache from 'chanjs/storage/cache.js';
+const customCache = new Cache({ maxSize: 50000, defaultTTL: 60000 });
 ```
 
+## 构造函数
+
+```javascript
+new Cache(opts = {})
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| opts.maxSize | number | 否 | 100000 | 缓存最大条目数 |
+| opts.defaultTTL | number | 否 | 300000 (5分钟) | 默认过期时间（毫秒） |
+
 ## 核心方法
-### 1. 设置缓存值
-#### `set(key, value, ttl = this.defaultTTL)`
-将键值对存入缓存，若缓存达到最大容量且键不存在，则自动淘汰最久未使用的条目，每次设置会更新访问时间。
 
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| key | string | - | 缓存键（非空字符串） |
-| value | * | - | 要缓存的任意类型数据 |
-| ttl | number | 实例默认TTL | 该缓存条目的过期时间（毫秒） |
+### 1. set - 写入缓存
+
+```javascript
+set(key, value, ttl = this.defaultTTL)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| key | string | 是 | - | 缓存键 |
+| value | any | 是 | - | 缓存值 |
+| ttl | number | 否 | defaultTTL | 过期时间（毫秒），<=0 视为永久存储 |
+
+**示例**
 
-**示例**：
 ```javascript
-// 设置60秒后过期的缓存
-customCache.set('user:123', { name: '张三', age: 20 }, 60000);
+import { cache } from 'chanjs';
+
+// 设置 60 秒过期的缓存
+cache.set('user:1001', { name: '张三' }, 60000);
 
-// 使用默认过期时间（5分钟）
-customCache.set('config:theme', { color: 'blue' });
+// 永久存储（ttl <= 0）
+cache.set('config:app', { version: '1.0' }, 0);
 ```
 
-### 2. 获取缓存值
-#### `get(key)`
-获取指定键的缓存值，若键不存在或已过期则返回 `null`；过期条目会自动删除，命中的条目会更新访问时间。
+### 2. get - 读取缓存
+
+```javascript
+get(key)
+```
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| key | string | 要获取的缓存键 |
+**参数**
 
-| 返回值 | 类型 | 说明 |
-|--------|------|------|
-| - | * | 缓存的原始值（命中且未过期）；`null`（未命中/已过期） |
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| key | string | 是 | 缓存键 |
+
+**返回值**
+
+- 缓存值：存在且未过期
+- `null`：不存在或已过期
+
+**示例**
 
-**示例**：
 ```javascript
-const user = customCache.get('user:123');
-if (user !== null) {
-  console.log('缓存命中:', user); // { name: '张三', age: 20 }
+const user = cache.get('user:1001');
+if (user) {
+  console.log('用户信息：', user);
 } else {
-  console.log('缓存未命中或已过期');
+  console.log('缓存不存在或已过期');
 }
 ```
 
-### 3. 删除缓存条目
-#### `del(key)`
-从缓存中删除指定键的条目，同时删除对应的访问记录。
+### 3. has - 检查存在
+
+```javascript
+has(key)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| key | string | 是 | 缓存键 |
+
+**返回值**
+
+- `true`：存在且未过期
+- `false`：不存在或已过期
+
+**示例**
+
+```javascript
+if (cache.has('user:1001')) {
+  console.log('缓存存在');
+}
+```
+
+### 4. del - 删除缓存
+
+```javascript
+del(key)
+```
+
+**示例**
+
+```javascript
+cache.del('user:1001');
+```
+
+### 5. clear - 清空所有
+
+```javascript
+clear()
+```
+
+**示例**
+
+```javascript
+cache.clear();
+```
+
+### 6. size - 获取数量
+
+```javascript
+size()
+```
+
+**返回值**
+
+缓存条目总数（近似值，包含未惰性清理的过期项）
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| key | string | 要删除的缓存键 |
+**示例**
 
-**示例**：
 ```javascript
-customCache.del('user:123'); // 删除指定缓存
+const count = cache.size();
+console.log(`缓存条目数：${count}`);
 ```
 
-### 4. 清空所有缓存
-#### `clear()`
-删除所有缓存条目和访问记录，清空整个缓存。
+### 7. incr - 自增（限流专用）
 
-**示例**：
 ```javascript
-customCache.clear(); // 清空所有缓存
+incr(key, ttlMs = 60000)
 ```
 
-### 5. 检查缓存键是否存在
-#### `has(key)`
-检查指定键是否存在且未过期，若已过期则自动删除条目并返回 `false`。
+**参数**
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| key | string | 要检查的缓存键 |
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| key | string | 是 | - | 缓存键 |
+| ttlMs | number | 否 | 60000 | 新建 key 的过期时间（毫秒），存量不续期 |
 
-| 返回值 | 类型 | 说明 |
-|--------|------|------|
-| - | boolean | `true`（存在且未过期）；`false`（不存在/已过期） |
+**返回值**
+
+自增后的值（number）
+
+**特性**
+
+- 新建 key 使用指定 TTL
+- 存量 key 不续期 TTL
+- 支持容量超限自动 LRU 淘汰
+
+**示例**
 
-**示例**：
 ```javascript
-if (customCache.has('config:theme')) {
-  console.log('缓存存在且有效');
+// 限流场景：60 秒内最多 100 次请求
+const count = cache.incr('rate:192.168.1.1', 60000);
+if (count > 100) {
+  console.log('请求过于频繁');
 } else {
-  console.log('缓存不存在或已过期');
+  console.log(`当前第 ${count} 次请求`);
 }
 ```
 
-### 6. 获取缓存有效条目数
-#### `size()`
-返回当前缓存中的有效条目数量（会先自动清理已过期条目）。
+### 8. incrAndExpire - 自增并设置过期时间
+
+```javascript
+incrAndExpire(key, ttlMs)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| key | string | 是 | 缓存键 |
+| ttlMs | number | 是 | 新建 key 的过期时间（毫秒） |
 
-| 返回值 | 类型 | 说明 |
-|--------|------|------|
-| - | number | 有效缓存条目数 |
+**返回值**
+
+自增后的值（number）
+
+**示例**
 
-**示例**：
 ```javascript
-console.log(`当前缓存有效条目数: ${customCache.size()}`);
+const count = cache.incrAndExpire('limit:api:1001', 30000);
 ```
 
-## 内部方法（私有）
-### 1. `_evictLRU()`
-淘汰最久未使用的缓存条目，当缓存达到最大容量时自动调用。遍历访问顺序 `Map`，找到访问时间最早的键并删除对应的缓存和访问记录。
+### 9. expire - 刷新过期时间
+
+```javascript
+expire(key, ttlMs)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| key | string | 是 | 缓存键 |
+| ttlMs | number | 是 | 新的过期时间（毫秒） |
+
+**返回值**
+
+- `true`：刷新成功
+- `false`：key 不存在或已过期
 
-### 2. `_cleanupExpired()`
-清理所有已过期的缓存条目，在调用 `size()` 方法时自动触发。遍历缓存 `Map`，删除所有过期的条目及对应的访问记录。
+**示例**
 
-## 预创建实例
-模块导出了一个默认的 `cache` 实例，使用默认配置（`maxSize=1000`，`defaultTTL=5分钟`），可直接使用：
 ```javascript
-import { cache } from 'chanjs/helper';
+// 续期 30 秒
+cache.expire('session:1001', 30000);
+```
+
+## 内部机制
+
+### LRU 淘汰
+
+- 使用 Map 的插入顺序特性
+- 访问时删除再插入，刷新到最新位置
+- 容量超限时淘汰最久未使用的条目
+
+### 惰性清理
+
+- 每 10 秒触发一次批量清理
+- 单次最多清理 1000 条，避免阻塞事件循环
+- 读取时检查过期状态，过期则删除
+
+### 容量配置
 
-// 直接使用默认实例
-cache.set('global:token', 'abc123', 1800000); // 30分钟过期
-const token = cache.get('global:token');
+- 默认最大容量：100,000 条
+- 达到容量上限时自动 LRU 淘汰
+- 可通过构造函数自定义
+
+## 使用场景
+
+### 1. 接口限流
+
+```javascript
+import { cache } from 'chanjs';
+
+function rateLimitMiddleware(req, res, next) {
+  const ip = req.ip;
+  const key = `rate:${ip}`;
+  const count = cache.incr(key, 60000); // 60 秒窗口
+  
+  if (count > 100) {
+    return res.status(429).json({
+      success: false,
+      code: 1009,
+      msg: '请求过于频繁'
+    });
+  }
+  
+  next();
+}
 ```
 
-## 核心特性
-1. **LRU 淘汰**：缓存达到最大容量时，自动删除最久未使用的条目；
-2. **TTL 过期**：支持自定义过期时间，过期条目自动清理；
-3. **自动清理**：获取缓存大小、检查键存在性时，自动清理过期条目；
-4. **访问更新**：每次设置/获取缓存，都会更新该条目的访问时间，保证 LRU 策略准确性；
-5. **内存安全**：通过最大条目数限制，避免缓存无限制占用内存。
+### 2. 会话缓存
+
+```javascript
+// 存储用户会话
+cache.set(`session:${userId}`, {
+  userId,
+  loginTime: Date.now(),
+  role: 'admin'
+}, 3600000); // 1 小时
+
+// 读取会话
+const session = cache.get(`session:${userId}`);
+```
+
+### 3. 数据缓存
+
+```javascript
+// 缓存数据库查询结果
+async function getUserWithCache(userId) {
+  const key = `user:${userId}`;
+  let user = cache.get(key);
+  
+  if (!user) {
+    user = await db('users').where({ id: userId }).first();
+    if (user) {
+      cache.set(key, user, 300000); // 缓存 5 分钟
+    }
+  }
+  
+  return user;
+}
+```
 
 ## 注意事项
-1. 缓存数据存储在内存中，应用重启后会丢失，不适用于持久化存储场景；
-2. 键必须为字符串类型，非字符串键可能导致不可预期的问题；
-3. 缓存值建议为可序列化的数据（如对象、字符串、数字等），避免存储复杂对象（如 DOM 元素、函数）导致内存泄漏；
-4. 若需高频清理过期条目，可手动调用 `size()` 方法触发清理（不建议频繁调用，会遍历全量缓存）。
+
+1. **内存占用**：缓存存储在内存中，应用重启后数据丢失
+2. **容量限制**：默认 10w 条目，超限自动 LRU 淘汰
+3. **过期精度**：惰性清理，过期时间可能有几秒误差
+4. **并发安全**：单线程环境，无需考虑并发问题
+5. **适用场景**：限流计数、临时缓存、会话存储等短 TTL 数据
+6. **不适用**：持久化存储、跨进程共享、大数据量存储
+
+## 与 Store 的关系
+
+- `Cache` 是底层内存缓存实现
+- `Store` 是统一存储适配层，封装了 `Cache` 和 Redis
+- 业务层推荐使用 `Store`，自动切换内存/Redis
+- 仅在使用纯内存场景时直接使用 `Cache`