# Cache 工具类文档
## 概述
`Cache` 是一个基于内存实现的 LRU（最近最少使用）缓存类，支持 TTL（生存时间）过期策略和自动过期清理机制。该类通过两个 `Map` 分别存储缓存数据和访问顺序，既保证了缓存的快速存取，又能实现 LRU 淘汰策略，适用于需要临时缓存数据且对内存使用有控制需求的场景。

## 安装与引入
从 `chanjs/helper` 模块中引入 `Cache` 类和默认实例：
```javascript
import { Cache } from 'chanjs/helper';
// 或引入预创建的默认缓存实例
import { cache } from 'chanjs/helper';
```

## 类构造器
### `constructor(options = {})`
创建缓存实例，初始化最大容量和默认过期时间。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| options.maxSize | number | 1000 | 缓存最大条目数，达到该数量时会自动淘汰最久未使用的条目 |
| options.defaultTTL | number | 300000（5分钟） | 默认过期时间（毫秒），未指定 TTL 时使用该值 |

**示例**：
```javascript
// 创建自定义配置的缓存实例
const customCache = new Cache({
  maxSize: 500,    // 最大缓存500条
  defaultTTL: 60000 // 默认1分钟过期
});

// 使用默认配置的缓存实例（maxSize=1000，defaultTTL=5分钟）
const defaultCache = new Cache();
```

## 核心方法
### 1. 设置缓存值
#### `set(key, value, ttl = this.defaultTTL)`
将键值对存入缓存，若缓存达到最大容量且键不存在，则自动淘汰最久未使用的条目，每次设置会更新访问时间。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| key | string | - | 缓存键（非空字符串） |
| value | * | - | 要缓存的任意类型数据 |
| ttl | number | 实例默认TTL | 该缓存条目的过期时间（毫秒） |

**示例**：
```javascript
// 设置60秒后过期的缓存
customCache.set('user:123', { name: '张三', age: 20 }, 60000);

// 使用默认过期时间（5分钟）
customCache.set('config:theme', { color: 'blue' });
```

### 2. 获取缓存值
#### `get(key)`
获取指定键的缓存值，若键不存在或已过期则返回 `null`；过期条目会自动删除，命中的条目会更新访问时间。

| 参数 | 类型 | 说明 |
|------|------|------|
| key | string | 要获取的缓存键 |

| 返回值 | 类型 | 说明 |
|--------|------|------|
| - | * | 缓存的原始值（命中且未过期）；`null`（未命中/已过期） |

**示例**：
```javascript
const user = customCache.get('user:123');
if (user !== null) {
  console.log('缓存命中:', user); // { name: '张三', age: 20 }
} else {
  console.log('缓存未命中或已过期');
}
```

### 3. 删除缓存条目
#### `del(key)`
从缓存中删除指定键的条目，同时删除对应的访问记录。

| 参数 | 类型 | 说明 |
|------|------|------|
| key | string | 要删除的缓存键 |

**示例**：
```javascript
customCache.del('user:123'); // 删除指定缓存
```

### 4. 清空所有缓存
#### `clear()`
删除所有缓存条目和访问记录，清空整个缓存。

**示例**：
```javascript
customCache.clear(); // 清空所有缓存
```

### 5. 检查缓存键是否存在
#### `has(key)`
检查指定键是否存在且未过期，若已过期则自动删除条目并返回 `false`。

| 参数 | 类型 | 说明 |
|------|------|------|
| key | string | 要检查的缓存键 |

| 返回值 | 类型 | 说明 |
|--------|------|------|
| - | boolean | `true`（存在且未过期）；`false`（不存在/已过期） |

**示例**：
```javascript
if (customCache.has('config:theme')) {
  console.log('缓存存在且有效');
} else {
  console.log('缓存不存在或已过期');
}
```

### 6. 获取缓存有效条目数
#### `size()`
返回当前缓存中的有效条目数量（会先自动清理已过期条目）。

| 返回值 | 类型 | 说明 |
|--------|------|------|
| - | number | 有效缓存条目数 |

**示例**：
```javascript
console.log(`当前缓存有效条目数: ${customCache.size()}`);
```

## 内部方法（私有）
### 1. `_evictLRU()`
淘汰最久未使用的缓存条目，当缓存达到最大容量时自动调用。遍历访问顺序 `Map`，找到访问时间最早的键并删除对应的缓存和访问记录。

### 2. `_cleanupExpired()`
清理所有已过期的缓存条目，在调用 `size()` 方法时自动触发。遍历缓存 `Map`，删除所有过期的条目及对应的访问记录。

## 预创建实例
模块导出了一个默认的 `cache` 实例，使用默认配置（`maxSize=1000`，`defaultTTL=5分钟`），可直接使用：
```javascript
import { cache } from 'chanjs/helper';

// 直接使用默认实例
cache.set('global:token', 'abc123', 1800000); // 30分钟过期
const token = cache.get('global:token');
```

## 核心特性
1. **LRU 淘汰**：缓存达到最大容量时，自动删除最久未使用的条目；
2. **TTL 过期**：支持自定义过期时间，过期条目自动清理；
3. **自动清理**：获取缓存大小、检查键存在性时，自动清理过期条目；
4. **访问更新**：每次设置/获取缓存，都会更新该条目的访问时间，保证 LRU 策略准确性；
5. **内存安全**：通过最大条目数限制，避免缓存无限制占用内存。

## 注意事项
1. 缓存数据存储在内存中，应用重启后会丢失，不适用于持久化存储场景；
2. 键必须为字符串类型，非字符串键可能导致不可预期的问题；
3. 缓存值建议为可序列化的数据（如对象、字符串、数字等），避免存储复杂对象（如 DOM 元素、函数）导致内存泄漏；
4. 若需高频清理过期条目，可手动调用 `size()` 方法触发清理（不建议频繁调用，会遍历全量缓存）。