yangy
665397ede7
- 新增OTA固件升级处理器，支持固件升级请求及黑名单过滤 - 引入设备持久化仓储，支持设备信息上报与活动记录 - 扩展数据模型，新增UserDevice与UserActive，支持设备版本跟踪 - 实现Redis到MySQL的异步数据同步任务 - 更新路由配置，集成新的API端点以支持OTA功能 - 优化架构图，反映新增的数据流与处理流程
422 lines
16 KiB
Markdown
422 lines
16 KiB
Markdown
# 缓存系统
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [cmd/server/main.go](file://cmd/server/main.go)
|
||
- [internal/cache/brand_cache.go](file://internal/cache/brand_cache.go)
|
||
- [internal/cache/model_cache.go](file://internal/cache/model_cache.go)
|
||
- [internal/cache/redis.go](file://internal/cache/redis.go)
|
||
- [internal/config/config.go](file://internal/config/config.go)
|
||
- [internal/config/redis.go](file://internal/config/redis.go)
|
||
- [internal/router/router.go](file://internal/router/router.go)
|
||
- [internal/repository/brand.go](file://internal/repository/brand.go)
|
||
- [internal/repository/model.go](file://internal/repository/model.go)
|
||
- [internal/handler/brand.go](file://internal/handler/brand.go)
|
||
- [internal/handler/model.go](file://internal/handler/model.go)
|
||
- [internal/model/brand.go](file://internal/model/brand.go)
|
||
- [internal/model/model.go](file://internal/model/model.go)
|
||
- [go.mod](file://go.mod)
|
||
</cite>
|
||
|
||
## 更新摘要
|
||
**变更内容**
|
||
- 新增完整的Redis缓存系统架构，包含BrandCache和ModelCache组件
|
||
- 实现TTL过期管理和自动缓存预热功能
|
||
- 添加缓存穿透防护和数据库降级机制
|
||
- 优化缓存键命名规范和数据序列化策略
|
||
- 增强缓存失效策略和数据一致性保证
|
||
- 实现智能缓存回写和错误处理机制
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [缓存策略设计](#缓存策略设计)
|
||
7. [依赖关系分析](#依赖关系分析)
|
||
8. [性能考虑](#性能考虑)
|
||
9. [故障排查指南](#故障排查指南)
|
||
10. [结论](#结论)
|
||
11. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件全面介绍Luxsin应用API的完整Redis缓存系统实现。该系统包含BrandCache和ModelCache两个核心组件，支持TTL过期管理、自动缓存预热、缓存穿透防护和数据库降级机制。系统通过三层架构设计（缓存层、仓库层、数据访问层）实现了高性能的数据访问模式，显著提升了品牌和型号数据的查询性能。
|
||
|
||
## 项目结构
|
||
完整的缓存系统分布在以下模块中：
|
||
- **缓存层**：BrandCache和ModelCache组件，负责Redis数据的读写和TTL管理
|
||
- **仓库层**：BrandRepository和ModelRepository，实现缓存与数据库的协调访问
|
||
- **应用层**：处理器和路由，提供RESTful API接口
|
||
- **配置层**：Redis配置加载和验证
|
||
- **模型层**：Brand和Model数据结构定义
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "应用入口"
|
||
MAIN["cmd/server/main.go<br/>启动与生命周期管理"]
|
||
WARMUP["warmUpCache<br/>缓存预热"]
|
||
end
|
||
subgraph "缓存层"
|
||
BRAND_CACHE["BrandCache<br/>品牌缓存组件"]
|
||
MODEL_CACHE["ModelCache<br/>型号缓存组件"]
|
||
REDIS_CLIENT["Redis Client<br/>连接管理"]
|
||
end
|
||
subgraph "仓库层"
|
||
BRAND_REPO["BrandRepository<br/>品牌数据访问"]
|
||
MODEL_REPO["ModelRepository<br/>型号数据访问"]
|
||
end
|
||
subgraph "应用层"
|
||
BRAND_HANDLER["BrandHandler<br/>品牌API"]
|
||
MODEL_HANDLER["ModelHandler<br/>型号API"]
|
||
ROUTER["Router<br/>路由注册"]
|
||
end
|
||
subgraph "配置层"
|
||
REDIS_CONFIG["RedisConfig<br/>配置加载"]
|
||
end
|
||
MAIN --> WARMUP
|
||
WARMUP --> BRAND_CACHE
|
||
WARMUP --> MODEL_CACHE
|
||
MAIN --> REDIS_CLIENT
|
||
BRAND_CACHE --> REDIS_CLIENT
|
||
MODEL_CACHE --> REDIS_CLIENT
|
||
BRAND_REPO --> BRAND_CACHE
|
||
MODEL_REPO --> MODEL_CACHE
|
||
BRAND_HANDLER --> BRAND_REPO
|
||
MODEL_HANDLER --> MODEL_REPO
|
||
ROUTER --> BRAND_HANDLER
|
||
ROUTER --> MODEL_HANDLER
|
||
MAIN --> REDIS_CONFIG
|
||
```
|
||
|
||
**图表来源**
|
||
- [cmd/server/main.go:25-131](file://cmd/server/main.go#L25-L131)
|
||
- [internal/cache/brand_cache.go:1-45](file://internal/cache/brand_cache.go#L1-L45)
|
||
- [internal/cache/model_cache.go:1-70](file://internal/cache/model_cache.go#L1-L70)
|
||
- [internal/repository/brand.go:1-100](file://internal/repository/brand.go#L1-L100)
|
||
- [internal/repository/model.go:1-181](file://internal/repository/model.go#L1-L181)
|
||
|
||
**章节来源**
|
||
- [cmd/server/main.go:25-131](file://cmd/server/main.go#L25-L131)
|
||
- [internal/cache/brand_cache.go:1-45](file://internal/cache/brand_cache.go#L1-L45)
|
||
- [internal/cache/model_cache.go:1-70](file://internal/cache/model_cache.go#L1-L70)
|
||
- [internal/repository/brand.go:1-100](file://internal/repository/brand.go#L1-L100)
|
||
- [internal/repository/model.go:1-181](file://internal/repository/model.go#L1-L181)
|
||
|
||
## 核心组件
|
||
|
||
### 缓存组件
|
||
- **BrandCache**：专门处理品牌数据的缓存，支持全量品牌列表缓存和TTL管理
|
||
- **ModelCache**：专门处理型号数据的缓存，支持按品牌分组缓存和全量缓存
|
||
- **Redis Client**：统一的Redis连接管理，支持连接池和超时配置
|
||
|
||
### 仓库组件
|
||
- **BrandRepository**：实现品牌数据的缓存优先访问模式，包含缓存穿透防护
|
||
- **ModelRepository**：实现型号数据的多级缓存策略，支持按品牌和全量缓存
|
||
|
||
### 处理器组件
|
||
- **BrandHandler**：提供品牌查询API，支持模糊匹配和Base64响应编码
|
||
- **ModelHandler**：提供型号查询API，支持按品牌和型号名称查询
|
||
|
||
**章节来源**
|
||
- [internal/cache/brand_cache.go:18-45](file://internal/cache/brand_cache.go#L18-L45)
|
||
- [internal/cache/model_cache.go:19-70](file://internal/cache/model_cache.go#L19-L70)
|
||
- [internal/repository/brand.go:14-100](file://internal/repository/brand.go#L14-L100)
|
||
- [internal/repository/model.go:14-181](file://internal/repository/model.go#L14-L181)
|
||
- [internal/handler/brand.go:13-49](file://internal/handler/brand.go#L13-L49)
|
||
- [internal/handler/model.go:13-50](file://internal/handler/model.go#L13-L50)
|
||
|
||
## 架构总览
|
||
缓存系统采用分层架构设计，实现了缓存优先的访问模式和智能降级机制：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "客户端"
|
||
participant Handler as "处理器"
|
||
participant Repo as "仓库层"
|
||
participant Cache as "缓存层"
|
||
participant DB as "数据库"
|
||
Client->>Handler : 发起查询请求
|
||
Handler->>Repo : 调用数据访问
|
||
Repo->>Cache : 尝试从缓存获取
|
||
alt 缓存命中
|
||
Cache-->>Repo : 返回缓存数据
|
||
Repo-->>Handler : 返回数据
|
||
Handler-->>Client : 返回响应
|
||
else 缓存未命中
|
||
Cache-->>Repo : 返回错误
|
||
Repo->>DB : 降级到数据库查询
|
||
DB-->>Repo : 返回数据库数据
|
||
Repo->>Cache : 写入缓存回写
|
||
Cache-->>Repo : 缓存写入成功
|
||
Repo-->>Handler : 返回数据
|
||
Handler-->>Client : 返回响应
|
||
end
|
||
```
|
||
|
||
**图表来源**
|
||
- [internal/repository/brand.go:23-52](file://internal/repository/brand.go#L23-L52)
|
||
- [internal/repository/model.go:23-79](file://internal/repository/model.go#L23-L79)
|
||
|
||
**章节来源**
|
||
- [internal/repository/brand.go:23-52](file://internal/repository/brand.go#L23-L52)
|
||
- [internal/repository/model.go:23-79](file://internal/repository/model.go#L23-L79)
|
||
|
||
## 详细组件分析
|
||
|
||
### BrandCache组件实现
|
||
BrandCache专门处理品牌数据的缓存，具有以下特性：
|
||
|
||
- **缓存键设计**：使用`brand:all`作为全量品牌列表的缓存键
|
||
- **TTL管理**：设置30分钟的过期时间，平衡内存使用和查询性能
|
||
- **数据序列化**：使用JSON格式存储品牌列表，支持快速序列化和反序列化
|
||
- **错误处理**：优雅处理缓存读取失败，支持降级到数据库
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class BrandCache {
|
||
-rdb : redis.Client
|
||
+GetAll(ctx) []Brand, error
|
||
+SetAll(ctx, []Brand) error
|
||
}
|
||
class RedisClient {
|
||
+Get(ctx, key) *Cmd
|
||
+Set(ctx, key, value, expiration) *Cmd
|
||
+Bytes() []byte, error
|
||
}
|
||
BrandCache --> RedisClient : "使用"
|
||
```
|
||
|
||
**图表来源**
|
||
- [internal/cache/brand_cache.go:18-45](file://internal/cache/brand_cache.go#L18-L45)
|
||
|
||
**章节来源**
|
||
- [internal/cache/brand_cache.go:13-45](file://internal/cache/brand_cache.go#L13-L45)
|
||
|
||
### ModelCache组件实现
|
||
ModelCache处理型号数据的多级缓存策略：
|
||
|
||
- **分组缓存**：按品牌名称建立独立的缓存键，如`model:brand:{brandName}`
|
||
- **全量缓存**：维护完整的型号列表缓存键`model:all`
|
||
- **TTL管理**：统一使用30分钟过期时间
|
||
- **键命名规范**：采用`前缀:类型:标识`的命名约定，便于管理和清理
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["型号查询开始"]) --> CheckBrand{"是否指定品牌?"}
|
||
CheckBrand --> |是| BrandCache["查询品牌缓存<br/>model:brand:{brandName}"]
|
||
CheckBrand --> |否| CheckModelName{"是否指定型号?"}
|
||
BrandCache --> ReturnBrand["返回品牌型号列表"]
|
||
CheckModelName --> |是| AllCache["查询全量缓存<br/>model:all"]
|
||
CheckModelName --> |否| Empty["返回空列表"]
|
||
AllCache --> Filter["应用层模糊过滤"]
|
||
Filter --> ReturnFiltered["返回过滤后的列表"]
|
||
ReturnBrand --> End(["结束"])
|
||
ReturnFiltered --> End
|
||
Empty --> End
|
||
```
|
||
|
||
**图表来源**
|
||
- [internal/cache/model_cache.go:27-69](file://internal/cache/model_cache.go#L27-L69)
|
||
|
||
**章节来源**
|
||
- [internal/cache/model_cache.go:13-70](file://internal/cache/model_cache.go#L13-L70)
|
||
|
||
### 缓存预热机制
|
||
系统在启动时自动执行缓存预热，确保服务启动后具备完整的缓存数据：
|
||
|
||
- **预热策略**：启动时从数据库加载所有品牌和型号数据到Redis
|
||
- **异步执行**：预热过程不影响服务启动时间
|
||
- **错误处理**：预热失败不会阻止服务正常启动，但会记录警告日志
|
||
- **数据完整性**：预热完成后记录缓存条目数量，便于监控和验证
|
||
|
||
**章节来源**
|
||
- [cmd/server/main.go:103-131](file://cmd/server/main.go#L103-L131)
|
||
- [cmd/server/main.go:67-68](file://cmd/server/main.go#L67-L68)
|
||
|
||
### 缓存穿透防护
|
||
系统实现了多层次的缓存穿透防护机制：
|
||
|
||
- **缓存空值处理**：当数据库查询结果为空时，仍会写入空值缓存，防止重复查询
|
||
- **降级机制**：缓存读取失败时自动降级到数据库查询
|
||
- **错误隔离**：缓存异常不会影响整体服务的可用性
|
||
- **日志记录**：记录缓存访问失败和降级事件，便于问题排查
|
||
|
||
**章节来源**
|
||
- [internal/repository/brand.go:34-52](file://internal/repository/brand.go#L34-L52)
|
||
- [internal/repository/model.go:27-79](file://internal/repository/model.go#L27-L79)
|
||
|
||
### 缓存回写机制
|
||
系统实现了智能的缓存回写机制，确保数据的一致性和新鲜度：
|
||
|
||
- **回写时机**：在数据库查询成功后，将数据写回到相应的缓存位置
|
||
- **回写策略**：根据查询类型选择合适的缓存回写策略
|
||
- **错误处理**：缓存回写失败时记录日志但不影响主流程
|
||
- **性能优化**：避免重复查询相同数据，提升整体查询性能
|
||
|
||
**章节来源**
|
||
- [internal/repository/brand.go:44-51](file://internal/repository/brand.go#L44-L51)
|
||
- [internal/repository/model.go:44-74](file://internal/repository/model.go#L44-L74)
|
||
|
||
## 缓存策略设计
|
||
|
||
### TTL过期管理
|
||
- **过期时间**：所有缓存数据设置30分钟过期时间
|
||
- **过期策略**：使用Redis的TTL机制自动清理过期数据
|
||
- **内存管理**：合理的过期时间平衡内存使用和查询性能
|
||
- **数据新鲜度**：定期过期确保缓存数据与数据库保持同步
|
||
|
||
### 键命名规范
|
||
- **品牌缓存**：`brand:all` - 全量品牌列表
|
||
- **型号缓存**：`model:brand:{brandName}` - 按品牌分组的型号列表
|
||
- **全量型号**：`model:all` - 完整的型号列表
|
||
- **命名约定**：采用`类型:子类型:标识`的层次化命名
|
||
|
||
### 数据序列化策略
|
||
- **JSON格式**：使用标准JSON格式进行数据序列化
|
||
- **二进制存储**：Redis存储二进制数据，提高传输效率
|
||
- **错误处理**：序列化和反序列化失败时返回明确的错误信息
|
||
|
||
### 缓存查询策略
|
||
- **品牌查询**：优先从缓存获取全量品牌列表，支持应用层模糊过滤
|
||
- **型号查询**：根据查询条件选择合适的缓存策略
|
||
- **缓存优先**：尽可能从缓存获取数据，减少数据库压力
|
||
- **降级保护**：缓存失败时自动降级到数据库查询
|
||
|
||
**章节来源**
|
||
- [internal/cache/brand_cache.go:13-16](file://internal/cache/brand_cache.go#L13-L16)
|
||
- [internal/cache/model_cache.go:13-17](file://internal/cache/model_cache.go#L13-L17)
|
||
- [internal/cache/brand_cache.go:38-44](file://internal/cache/brand_cache.go#L38-L44)
|
||
- [internal/cache/model_cache.go:43-69](file://internal/cache/model_cache.go#L43-L69)
|
||
|
||
## 依赖关系分析
|
||
缓存系统各组件之间的依赖关系清晰明确：
|
||
|
||
```mermaid
|
||
graph LR
|
||
MAIN["cmd/server/main.go"] --> CACHE["internal/cache/*"]
|
||
MAIN --> REPO["internal/repository/*"]
|
||
REPO --> CACHE
|
||
REPO --> MODEL["internal/model/*"]
|
||
HANDLER["internal/handler/*"] --> REPO
|
||
ROUTER["internal/router/router.go"] --> HANDLER
|
||
CONFIG["internal/config/redis.go"] --> MAIN
|
||
CACHE --> REDIS["github.com/redis/go-redis/v9"]
|
||
REPO --> REDIS
|
||
```
|
||
|
||
**图表来源**
|
||
- [cmd/server/main.go:13-23](file://cmd/server/main.go#L13-L23)
|
||
- [internal/repository/brand.go:3-12](file://internal/repository/brand.go#L3-L12)
|
||
- [internal/router/router.go:3-14](file://internal/router/router.go#L3-L14)
|
||
|
||
**章节来源**
|
||
- [cmd/server/main.go:13-23](file://cmd/server/main.go#L13-L23)
|
||
- [internal/repository/brand.go:3-12](file://internal/repository/brand.go#L3-L12)
|
||
- [internal/router/router.go:3-14](file://internal/router/router.go#L3-L14)
|
||
|
||
## 性能考虑
|
||
|
||
### 缓存命中率优化
|
||
- **预热策略**：启动时预热常用数据，提高初始命中率
|
||
- **分层缓存**：按查询频率和数据特征设计不同的缓存策略
|
||
- **TTL调优**：根据数据更新频率调整过期时间
|
||
|
||
### 内存使用优化
|
||
- **数据压缩**：JSON序列化相比其他格式更节省空间
|
||
- **键空间管理**：合理的键命名减少内存碎片
|
||
- **过期清理**：Redis自动清理过期数据，无需手动干预
|
||
|
||
### 网络延迟优化
|
||
- **连接复用**：Redis客户端自动管理连接池
|
||
- **批量操作**：支持Pipeline批量执行多个命令
|
||
- **超时控制**：每个操作都有明确的超时限制
|
||
|
||
### 错误处理与容错
|
||
- **降级机制**：缓存失败时自动降级到数据库
|
||
- **重试策略**：关键操作支持有限次重试
|
||
- **监控告警**：缓存异常时触发告警通知
|
||
|
||
## 故障排查指南
|
||
|
||
### 缓存相关问题
|
||
- **缓存不生效**
|
||
- 检查Redis连接配置是否正确
|
||
- 验证缓存键是否符合预期格式
|
||
- 确认TTL设置是否合理
|
||
|
||
- **缓存数据过期**
|
||
- 检查TTL配置和Redis过期策略
|
||
- 验证数据更新后是否及时刷新缓存
|
||
- 查看缓存预热是否成功执行
|
||
|
||
- **缓存穿透**
|
||
- 检查空值缓存是否正确设置
|
||
- 验证降级机制是否正常工作
|
||
- 查看数据库查询是否频繁失败
|
||
|
||
### 性能问题诊断
|
||
- **查询缓慢**
|
||
- 分析缓存命中率和未命中率
|
||
- 检查数据库查询性能
|
||
- 监控Redis连接池使用情况
|
||
|
||
- **内存占用过高**
|
||
- 检查缓存键数量和大小
|
||
- 验证TTL设置是否合理
|
||
- 分析数据更新频率
|
||
|
||
### 缓存回写问题
|
||
- **缓存未更新**
|
||
- 检查缓存回写逻辑是否正确执行
|
||
- 验证缓存键是否正确生成
|
||
- 查看回写错误日志
|
||
|
||
- **数据不一致**
|
||
- 检查缓存过期时间设置
|
||
- 验证数据库更新后是否及时回写
|
||
- 分析并发访问时的数据一致性
|
||
|
||
**章节来源**
|
||
- [cmd/server/main.go:103-131](file://cmd/server/main.go#L103-L131)
|
||
- [internal/repository/brand.go:34-52](file://internal/repository/brand.go#L34-L52)
|
||
- [internal/repository/model.go:27-79](file://internal/repository/model.go#L27-L79)
|
||
|
||
## 结论
|
||
Luxsin应用API的缓存系统实现了完整的Redis缓存解决方案，包含以下关键特性：
|
||
|
||
- **完整的组件体系**：BrandCache和ModelCache提供了专业的缓存功能
|
||
- **智能的缓存策略**：支持TTL管理、自动预热和多级缓存
|
||
- **可靠的降级机制**：缓存失败时自动降级到数据库，确保服务可用性
|
||
- **完善的回写机制**：智能缓存回写确保数据一致性
|
||
- **良好的扩展性**：清晰的架构设计便于添加新的缓存组件
|
||
|
||
建议在后续版本中进一步完善监控指标、缓存统计和动态配置功能，以提升系统的可观测性和运维效率。
|
||
|
||
## 附录
|
||
|
||
### 缓存配置参数
|
||
- **TTL设置**：30分钟（brandTTL = 30 * time.Minute）
|
||
- **Redis连接**：默认数据库1，端口6379
|
||
- **缓存键格式**：
|
||
- 品牌：`brand:all`
|
||
- 型号：`model:brand:{brandName}`
|
||
- 全量型号：`model:all`
|
||
|
||
### API接口说明
|
||
- **品牌查询**：`GET /audio/getBrand?brandName={name}&base64=true`
|
||
- **型号查询**：`GET /audio/getModel?brandName={name}&modelName={name}&base64=true`
|
||
|
||
### 监控指标
|
||
- 缓存命中率
|
||
- 缓存未命中率
|
||
- 缓存写入成功率
|
||
- 数据库查询次数
|
||
- Redis连接池使用情况
|
||
- 缓存回写成功率
|
||
|
||
**章节来源**
|
||
- [internal/cache/brand_cache.go:13-16](file://internal/cache/brand_cache.go#L13-L16)
|
||
- [internal/cache/model_cache.go:13-17](file://internal/cache/model_cache.go#L13-L17)
|
||
- [internal/handler/brand.go:25-48](file://internal/handler/brand.go#L25-L48)
|
||
- [internal/handler/model.go:25-49](file://internal/handler/model.go#L25-L49) |