hotime/.cursor/plans/缓存表模式配置_49ed5633.plan.md

---
name: 缓存表模式配置
overview: 为 CacheDb 添加 mode 配置项，支持 "new"（默认，只用新表）和 "compatible"（写新读老）两种模式，并更新配置说明。
todos:
  - id: add-mode-field
    content: 在 CacheDb 结构体中添加 Mode 字段
    status: completed
  - id: modify-init
    content: 修改 initDbTable，根据 Mode 决定是否迁移删除老表
    status: completed
    dependencies:
      - add-mode-field
  - id: add-legacy-get
    content: 添加 getLegacy 方法读取老表数据（unix时间戳格式）
    status: completed
    dependencies:
      - add-mode-field
  - id: modify-get
    content: 修改 get 方法，compatible 模式下回退读取老表
    status: completed
    dependencies:
      - add-legacy-get
  - id: modify-set
    content: 修改 set 方法，compatible 模式下写新表后删除老表同key记录
    status: completed
    dependencies:
      - add-mode-field
  - id: modify-delete
    content: 修改 delete 方法，compatible 模式下同时删除新表和老表
    status: completed
    dependencies:
      - add-mode-field
  - id: update-cache-init
    content: 在 cache.go Init 方法中读取 mode 配置
    status: completed
    dependencies:
      - add-mode-field
  - id: update-config-note
    content: 在 var.go ConfigNote 中添加 mode 配置说明
    status: completed
  - id: add-cache-test
    content: 在 example/main.go 中添加缓存测试路由
    status: completed
    dependencies:
      - modify-get
      - modify-set
      - modify-delete
      - update-cache-init
  - id: todo-1769763169689-k7t9twp5t
    content: |
      QUICKSTART.md 更新：缓存配置部分需要添加 mode 和 history 配置说明
    status: pending
---

# 缓存表模式配置实现计划

## 需求概述

在 [`cache/cache_db.go`](cache/cache_db.go) 中实现两种缓存表模式：

- **new**（默认）：只使用新的 `hotime_cache` 表，自动迁移老表数据
- **compatible**：写入新表，读取时先查新表再查老表，老数据自然过期消亡

## 实现步骤

### 1. 修改 CacheDb 结构体

在 [`cache/cache_db.go`](cache/cache_db.go) 中添加 `Mode` 字段：

```go
type CacheDb struct {
    TimeOut    int64
    DbSet      bool
    SessionSet bool
    HistorySet bool
    Mode       string // "new"(默认) 或 "compatible"
    Db         HoTimeDBInterface
    // ...
}
```

### 2. 修改初始化逻辑 initDbTable

- **new 模式**：创建新表、迁移老表数据，**但不删除老表**（删除交给用户手动操作，更安全）
- **compatible 模式**：创建新表，不迁移也不删除老表

两种模式都不自动删除老表，避免自动删除造成数据丢失风险

### 3. 修改 get 方法

- **new 模式**：只从新表读取
- **compatible 模式**：先从新表读取，如果没有再从老表读取

需要新增 `getLegacy` 方法来读取老表数据，该方法需要：

1. 查询老表数据
2. 检查 `endtime`（unix 时间戳）是否过期
3. 如果过期：删除该条记录，返回 nil
4. 如果未过期：返回数据

### 4. 修改 set 方法（写新删老）

- **new 模式**：只写新表（老表保留但不再管理）
- **compatible 模式**：写入新表 + 删除老表中相同 key 的记录

这样可以主动加速老数据消亡，而不是等自然过期。

### 5. 修改 delete 方法

- **new 模式**：只删除新表（老表保留但不再管理）
- **compatible 模式**：同时删除新表和老表中的 key

这是必要的，否则删除新表后，下次读取会回退读到老表的数据，造成"删不掉"的问题。

需要新增 `deleteLegacy` 方法处理老表删除逻辑

### 6. 更新缓存初始化

在 [`cache/cache.go`](cache/cache.go) 的 `Init` 方法中读取 `mode` 配置：

```go
that.dbCache = &CacheDb{
    // ...
    Mode: db.GetString("mode"), // 读取 mode 配置
}
```

### 7. 更新配置说明

在 [`var.go`](var.go) 的 `ConfigNote` 中添加 `mode` 配置说明：

```go
"db": Map{
    // ...
    "mode": "默认new，非必须，new为只使用新表（自动迁移老数据），compatible为兼容模式（写新表读老表，老数据自然过期）",
}
```

### 8. 编写测试

在 [`example/main.go`](example/main.go) 中添加缓存测试路由，测试覆盖：

**new 模式测试：**

- 基础读写：set/get/delete 正常工作
- 过期测试：设置短过期时间，验证过期后读取返回 nil
- 数据迁移：验证老表数据能正确迁移到新表
- 老表保留：验证迁移后老表仍存在（不自动删除）

**compatible 模式测试：**

- 新表读写：优先从新表读取
- 老表回退：新表没有时从老表读取
- 过期检测：读取老表过期数据时返回 nil 并删除该记录
- 写新删老：写入新表后老表同 key 记录被删除
- 删除双表：删除操作同时删除新表和老表记录
- 通配删除：`key*` 格式删除测试

**边界情况测试：**

- 空值处理：nil 值的 set/get
- 不存在的 key 读取
- 重复 set 同一个 key
- 超时时间参数测试（默认/自定义）

## 架构图

```mermaid
flowchart TD
    subgraph Config[配置]
        ModeNew["mode: new (默认)"]
        ModeCompat["mode: compatible"]
    end
    
    subgraph NewMode[new模式]
        N1[初始化] --> N2[创建新表]
        N2 --> N3{老表存在?}
        N3 -->|是| N4[迁移数据到新表]
        N4 --> N5[保留老表由人工删除]
        N3 -->|否| N6[完成]
        N5 --> N6
        
        NR[读取] --> NR1[只查询新表]
        NW[写入] --> NW1[只写入新表]
        ND[删除] --> ND1[只删除新表记录]
    end
    
    subgraph CompatMode[compatible模式]
        C1[初始化] --> C2[创建新表]
        C2 --> C3[保留老表]
        
        CR[读取] --> CR1[查询新表]
        CR1 -->|未找到| CR2[查询老表]
        CR2 --> CR3{过期?}
        CR3 -->|是| CR4[删除老表记录]
        CR4 --> CR5[返回nil]
        CR3 -->|否| CR6[返回数据]
        
        CW[写入] --> CW1[写入新表]
        CW1 --> CW2[删除老表同key]
        
        CD[删除] --> CD1[删除新表记录]
        CD1 --> CD2[删除老表记录]
    end
```

## 文件修改列表

| 文件 | 修改内容 |

|------|----------|

| [`cache/cache_db.go`](cache/cache_db.go) | 添加 Mode 字段、修改 initDbTable、添加 getLegacy（含过期检测删除）、修改 get、修改 set（写新删老）、修改 delete |

| [`cache/cache.go`](cache/cache.go) | 读取 mode 配置 |

| [`var.go`](var.go) | ConfigNote 添加 mode 说明 |

| [`example/main.go`](example/main.go) | 添加缓存测试路由 |

| [`example/config/config.json`](example/config/config.json) | 可选：添加 mode 配置示例 |