feat(cache): 实现 RoutingCache 和 StatsBuffer 优化数据库写入
- 新增 RoutingCache 组件,使用 sync.Map 缓存 Provider 和 Model - 新增 StatsBuffer 组件,使用 sync.Map + atomic.Int64 缓冲统计数据 - 扩展 StatsRepository.BatchUpdate 支持批量增量更新 - 改造 RoutingService/StatsService/ProviderService/ModelService 集成缓存 - 更新 usage-statistics spec,新增 routing-cache 和 stats-buffer spec - 新增单元测试覆盖缓存命中/失效/并发场景
This commit is contained in:
156
openspec/specs/stats-buffer/spec.md
Normal file
156
openspec/specs/stats-buffer/spec.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# Stats Buffer
|
||||
|
||||
## Purpose
|
||||
|
||||
TBD - 为统计数据提供内存缓冲,优化写入性能。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: StatsBuffer 内存缓冲
|
||||
|
||||
系统 SHALL 为统计数据提供内存缓冲,使用 sync.Map + atomic.Int64 进行计数。
|
||||
|
||||
#### Scenario: 缓冲数据结构
|
||||
|
||||
- **WHEN** 创建 StatsBuffer
|
||||
- **THEN** SHALL 使用 sync.Map 存储计数器(key = providerID/modelName/date)
|
||||
- **THEN** SHALL 使用 atomic.Int64 进行计数
|
||||
- **THEN** SHALL 支持配置刷新间隔和阈值
|
||||
|
||||
### Requirement: 原子计数
|
||||
|
||||
StatsBuffer SHALL 使用原子操作进行计数。
|
||||
|
||||
#### Scenario: Increment 计数
|
||||
|
||||
- **WHEN** 调用 StatsBuffer.Increment
|
||||
- **THEN** SHALL 使用 atomic.AddInt64 增加计数
|
||||
- **THEN** SHALL 无锁操作
|
||||
- **THEN** SHALL 线程安全
|
||||
|
||||
#### Scenario: Increment 创建计数器
|
||||
|
||||
- **WHEN** 调用 StatsBuffer.Increment 且计数器不存在
|
||||
- **THEN** SHALL 使用 sync.Map.LoadOrStore 创建计数器
|
||||
- **THEN** SHALL 初始化计数器为 0
|
||||
- **THEN** SHALL 原子增加计数
|
||||
|
||||
#### Scenario: 并发计数
|
||||
|
||||
- **WHEN** 多个 goroutine 并发 Increment
|
||||
- **THEN** SHALL 计数准确
|
||||
- **THEN** SHALL 无竞态条件
|
||||
|
||||
### Requirement: 定时刷新
|
||||
|
||||
StatsBuffer SHALL 支持定时刷新到数据库。
|
||||
|
||||
#### Scenario: 定时刷新触发
|
||||
|
||||
- **WHEN** 后台刷新协程运行
|
||||
- **THEN** SHALL 每隔 flushInterval 触发刷新
|
||||
- **THEN** SHALL 调用 StatsRepository.BatchUpdate 写入数据库
|
||||
|
||||
#### Scenario: 刷新间隔配置
|
||||
|
||||
- **WHEN** 创建 StatsBuffer
|
||||
- **THEN** 默认 flushInterval 为 5 秒
|
||||
- **THEN** 可通过 WithFlushInterval 选项配置
|
||||
|
||||
### Requirement: 阈值触发刷新
|
||||
|
||||
StatsBuffer SHALL 支持累计阈值触发刷新。
|
||||
|
||||
#### Scenario: 阈值触发
|
||||
|
||||
- **WHEN** 累计计数达到 flushThreshold
|
||||
- **THEN** SHALL 异步触发刷新
|
||||
- **THEN** SHALL 不阻塞请求
|
||||
|
||||
#### Scenario: 阈值配置
|
||||
|
||||
- **WHEN** 创建 StatsBuffer
|
||||
- **THEN** 默认 flushThreshold 为 100
|
||||
- **THEN** 可通过 WithFlushThreshold 选项配置
|
||||
|
||||
### Requirement: 批量写入数据库
|
||||
|
||||
StatsBuffer SHALL 批量写入统计数据到数据库。
|
||||
|
||||
#### Scenario: 批量写入
|
||||
|
||||
- **WHEN** 刷新触发
|
||||
- **THEN** SHALL 遍历所有计数器
|
||||
- **THEN** SHALL 使用 atomic.SwapInt64(counter, 0) 获取并清零计数器
|
||||
- **THEN** SHALL 调用 StatsRepository.BatchUpdate 批量写入
|
||||
- **THEN** SHALL 重置 totalCount 为 0
|
||||
|
||||
#### Scenario: SwapInt64 清零计数器
|
||||
|
||||
- **WHEN** flush 收集计数器
|
||||
- **THEN** SHALL 使用 SwapInt64 原子操作获取当前计数并清零
|
||||
- **THEN** SHALL 保证计数不丢失(新计数会累加到已清零的计数器)
|
||||
- **THEN** SHALL 不阻塞后续 Increment 操作
|
||||
|
||||
#### Scenario: 写入失败保留计数器
|
||||
|
||||
- **WHEN** BatchUpdate 失败
|
||||
- **THEN** SHALL 将计数加回计数器(使用 atomic.AddInt64)
|
||||
- **THEN** SHALL 记录错误日志
|
||||
- **THEN** SHALL 继续处理其他条目
|
||||
|
||||
### Requirement: 优雅关闭
|
||||
|
||||
StatsBuffer SHALL 支持优雅关闭,确保最后的统计写入数据库。
|
||||
|
||||
#### Scenario: Stop 等待刷新完成
|
||||
|
||||
- **WHEN** 调用 StatsBuffer.Stop
|
||||
- **THEN** SHALL 停止后台刷新协程
|
||||
- **THEN** SHALL 执行最后一次刷新
|
||||
- **THEN** SHALL 等待刷新完成
|
||||
- **THEN** SHALL 保证统计数据不丢失
|
||||
|
||||
#### Scenario: 无超时
|
||||
|
||||
- **WHEN** Stop 等待刷新
|
||||
- **THEN** SHALL 无超时限制
|
||||
- **THEN** SHALL 等待刷新完成
|
||||
|
||||
### Requirement: StatsService 使用缓冲
|
||||
|
||||
StatsService SHALL 使用 StatsBuffer 进行统计记录。
|
||||
|
||||
#### Scenario: Record 使用缓冲
|
||||
|
||||
- **WHEN** 调用 StatsService.Record
|
||||
- **THEN** SHALL 调用 StatsBuffer.Increment
|
||||
- **THEN** SHALL 不直接调用 StatsRepository.Record
|
||||
- **THEN** SHALL 立即返回,不阻塞
|
||||
|
||||
### Requirement: StatsRepository 扩展
|
||||
|
||||
StatsRepository SHALL 新增 BatchUpdate 方法。
|
||||
|
||||
#### Scenario: BatchUpdate 方法
|
||||
|
||||
- **WHEN** 调用 StatsRepository.BatchUpdate
|
||||
- **THEN** SHALL 使用事务更新或创建统计记录
|
||||
- **THEN** SHALL 使用 request_count + delta 更新
|
||||
- **THEN** SHALL 支持批量增量更新
|
||||
|
||||
### Requirement: 并发安全
|
||||
|
||||
StatsBuffer SHALL 支持并发访问。
|
||||
|
||||
#### Scenario: 并发 Increment 和 flush
|
||||
|
||||
- **WHEN** 并发 Increment 和 flush
|
||||
- **THEN** SHALL 无竞态条件
|
||||
- **THEN** SHALL 计数准确(可能延迟到下次 flush)
|
||||
|
||||
#### Scenario: flush 期间 Increment
|
||||
|
||||
- **WHEN** flush 正在执行
|
||||
- **THEN** 新的 Increment SHALL 继续计数
|
||||
- **THEN** SHALL 不会丢失计数
|
||||
Reference in New Issue
Block a user