feat(cache): 完善缓存系统实现及集成数据访问层

- 新增BrandCache与ModelCache，实现多级缓存和TTL管理 - 引入缓存预热机制，启动时自动加载品牌与型号数据 - 实现缓存穿透防护和数据库降级策略，提升服务稳定性 - 优化缓存键命名和数据序列化策略，增强管理便捷性 - 数据访问层新增缓存感知查询，品牌与型号仓库支持缓存优先 - 调整整体架构，增强组件解耦及依赖注入链路清晰度 - 提供详细的性能优化建议和故障排查指南 - 补充监控指标说明，便于后续运维与监控扩展
2026-05-28 15:30:05 +08:00
parent 36c6ca2766
commit b2c11adeba
5 changed files with 1086 additions and 596 deletions
@@ -20,48 +20,59 @@
 - [internal/middleware/request_id.go](file://internal/middleware/request_id.go)
 - [internal/model/brand.go](file://internal/model/brand.go)
 - [internal/model/model.go](file://internal/model/model.go)
+- [internal/cache/brand_cache.go](file://internal/cache/brand_cache.go)
+- [internal/cache/model_cache.go](file://internal/cache/model_cache.go)
 </cite>

+## 更新摘要
+**变更内容**
+- 更新依赖注入模式：所有处理器现在通过构造函数接收依赖项实例
+- 新增仓储层依赖：BrandHandler 和 ModelHandler 现在依赖仓储实例而非直接数据库连接
+- 更新路由装配：路由在启动时集中装配依赖并传递给处理器
+- 简化处理器实现：移除了对全局数据库连接的直接依赖
+
 ## 目录
 1. [简介](#简介)
 2. [项目结构](#项目结构)
 3. [核心组件](#核心组件)
 4. [架构总览](#架构总览)
 5. [详细组件分析](#详细组件分析)
-6. [依赖分析](#依赖分析)
-7. [性能考虑](#性能考虑)
-8. [故障排查指南](#故障排查指南)
-9. [结论](#结论)
-10. [附录](#附录)
+6. [依赖注入模式详解](#依赖注入模式详解)
+7. [依赖分析](#依赖分析)
+8. [性能考虑](#性能考虑)
+9. [故障排查指南](#故障排查指南)
+10. [结论](#结论)
+11. [附录](#附录)

 ## 简介
-本文件面向 Luxsin 应用 API 的业务处理器模块，系统性梳理各处理器的职责、接口设计与实现细节，覆盖 BrandHandler、ModelHandler、ModelListHandler、DeviceHandler 与 HealthHandler。文档同时阐述依赖注入模式、错误处理机制、响应格式化策略，以及与 Gin 框架的集成方式；并通过流程图与类图展示处理器间的协作关系与数据流转过程，帮助初学者快速上手，同时为高级开发者提供深入的技术参考。
+本文件面向 Luxsin 应用 API 的业务处理器模块，系统性梳理各处理器的职责、接口设计与实现细节，覆盖 BrandHandler、ModelHandler、ModelListHandler、DeviceHandler 与 HealthHandler。文档重点阐述新的依赖注入模式、错误处理机制、响应格式化策略，以及与 Gin 框架的集成方式；并通过流程图与类图展示处理器间的协作关系与数据流转过程，帮助初学者快速上手，同时为高级开发者提供深入的技术参考。

 ## 项目结构
-业务处理器位于 internal/handler 目录，围绕“控制器-仓储-搜索-缓存-响应”的分层组织，配合中间件与路由装配，形成清晰的控制流与依赖注入入口。
+业务处理器位于 internal/handler 目录，采用依赖注入模式，围绕"控制器-仓储-搜索-缓存-响应"的分层组织，配合中间件与路由装配，形成清晰的控制流与依赖注入入口。

 ```mermaid
 graph TB
 subgraph "应用入口"
 MAIN["cmd/server/main.go<br/>启动与配置加载"]
-end
+END
 subgraph "路由与中间件"
-ROUTER["internal/router/router.go<br/>路由注册与中间件装配"]
+ROUTER["internal/router/router.go<br/>路由注册与依赖注入"]
 CORS["internal/middleware/cors.go"]
 LOGMW["internal/middleware/logger.go"]
 REQID["internal/middleware/request_id.go"]
 end
 subgraph "业务处理器"
-HEALTH["internal/handler/health.go"]
-BRAND["internal/handler/brand.go"]
-MODEL["internal/handler/model.go"]
-MODELLIST["internal/handler/model_list.go"]
-DEVICE["internal/handler/device.go"]
+HEALTH["internal/handler/health.go<br/>NewHealthHandler()"]
+BRAND["internal/handler/brand.go<br/>NewBrandHandler(brandRepo, log)"]
+MODEL["internal/handler/model.go<br/>NewModelHandler(modelRepo, log)"]
+MODELLIST["internal/handler/model_list.go<br/>NewModelListHandler(searchClient, log)"]
+DEVICE["internal/handler/device.go<br/>NewDeviceHandler(redis, log)"]
 end
 subgraph "基础设施"
 RESP["internal/response/response.go<br/>统一响应体"]
 ENCODE["pkg/encode/base64.go<br/>自定义Base64编码"]
 SEARCH["internal/search/meilisearch.go<br/>Meilisearch客户端"]
+CACHE["internal/cache/*<br/>Redis缓存"]
 end
 MAIN --> ROUTER
 ROUTER --> CORS
@@ -77,43 +88,42 @@ MODEL --> RESP
 MODELLIST --> RESP
 DEVICE --> RESP
 MODELLIST --> SEARCH
+BRAND --> CACHE
+MODEL --> CACHE
 BRAND --> ENCODE
 MODEL --> ENCODE
 MODELLIST --> ENCODE
 ```

-图表来源
- [cmd/server/main.go:22-96](file://cmd/server/main.go#L22-L96)
- [internal/router/router.go:14-42](file://internal/router/router.go#L14-L42)
- [internal/handler/health.go:8-19](file://internal/handler/health.go#L8-L19)
- [internal/handler/brand.go:14-50](file://internal/handler/brand.go#L14-L50)
- [internal/handler/model.go:14-51](file://internal/handler/model.go#L14-L51)
- [internal/handler/model_list.go:14-57](file://internal/handler/model_list.go#L14-L57)
- [internal/handler/device.go:14-85](file://internal/handler/device.go#L14-L85)
- [internal/response/response.go:9-37](file://internal/response/response.go#L9-L37)
- [pkg/encode/base64.go:8-52](file://pkg/encode/base64.go#L8-L52)
- [internal/search/meilisearch.go:13-46](file://internal/search/meilisearch.go#L13-L46)
+**图表来源**
+- [cmd/server/main.go:25-101](file://cmd/server/main.go#L25-L101)
+- [internal/router/router.go:16-52](file://internal/router/router.go#L16-L52)
+- [internal/handler/health.go:10](file://internal/handler/health.go#L10)
+- [internal/handler/brand.go:18](file://internal/handler/brand.go#L18)
+- [internal/handler/model.go:18](file://internal/handler/model.go#L18)
+- [internal/handler/model_list.go:19](file://internal/handler/model_list.go#L19)
+- [internal/handler/device.go:19](file://internal/handler/device.go#L19)

-章节来源
- [internal/router/router.go:14-42](file://internal/router/router.go#L14-L42)
- [cmd/server/main.go:22-96](file://cmd/server/main.go#L22-L96)
+**章节来源**
+- [internal/router/router.go:16-52](file://internal/router/router.go#L16-L52)
+- [cmd/server/main.go:25-101](file://cmd/server/main.go#L25-L101)

 ## 核心组件
- 健康检查处理器：提供轻量级健康状态返回，便于外部探活与编排。
- 品牌查询处理器：按品牌名模糊查询品牌列表，支持可选的自定义 Base64 响应。
- 型号查询处理器：按品牌或型号关键字查询型号列表，支持可选的自定义 Base64 响应。
- 型号检索处理器：基于 Meilisearch 执行全文检索，支持可选的自定义 Base64 响应。
- 设备上报处理器：接收设备信息（MAC、型号、版本、来源 IP），写入 Redis Hash。
+- **健康检查处理器**：提供轻量级健康状态返回，便于外部探活与编排。
+- **品牌查询处理器**：按品牌名模糊查询品牌列表，现在依赖 BrandRepository 实例。
+- **型号查询处理器**：按品牌或型号关键字查询型号列表，现在依赖 ModelRepository 实例。
+- **型号检索处理器**：基于 Meilisearch 执行全文检索，依赖搜索客户端实例。
+- **设备上报处理器**：接收设备信息（MAC、型号、版本、来源 IP），依赖 Redis 客户端。

-章节来源
+**章节来源**
 - [internal/handler/health.go:8-19](file://internal/handler/health.go#L8-L19)
- [internal/handler/brand.go:14-50](file://internal/handler/brand.go#L14-L50)
- [internal/handler/model.go:14-51](file://internal/handler/model.go#L14-L51)
- [internal/handler/model_list.go:14-57](file://internal/handler/model_list.go#L14-L57)
- [internal/handler/device.go:14-85](file://internal/handler/device.go#L14-L85)
+- [internal/handler/brand.go:13-23](file://internal/handler/brand.go#L13-L23)
+- [internal/handler/model.go:13-23](file://internal/handler/model.go#L13-L23)
+- [internal/handler/model_list.go:14-24](file://internal/handler/model_list.go#L14-L24)
+- [internal/handler/device.go:14-24](file://internal/handler/device.go#L14-L24)

 ## 架构总览
-下图展示从请求进入至响应返回的关键路径，以及处理器与仓储、搜索、缓存、日志等组件的交互。
+下图展示从请求进入至响应返回的关键路径，以及处理器与仓储、搜索、缓存、日志等组件的交互，体现了完整的依赖注入架构。

 ```mermaid
 sequenceDiagram
@@ -130,149 +140,162 @@ alt "品牌/型号查询"
 H->>REPO : "List(ctx, filters)"
 REPO-->>H : "结果集"
 else "型号检索"
-H->>S : "SearchWithContext(key, opts)"
+H->>S : "ModelList(ctx, key, count)"
 S-->>H : "命中结果"
 else "设备上报"
-H->>RC : "HSet(mac, json)"
+H->>RC : "HSet(ctx, key, mac, json)"
 RC-->>H : "OK 或错误"
 end
 H->>L : "记录日志/错误"
 H-->>C : "JSON 或自定义Base64响应"
 ```

-图表来源
- [internal/router/router.go:27-38](file://internal/router/router.go#L27-L38)
- [internal/handler/brand.go:26-49](file://internal/handler/brand.go#L26-L49)
- [internal/handler/model.go:26-50](file://internal/handler/model.go#L26-L50)
- [internal/handler/model_list.go:26-56](file://internal/handler/model_list.go#L26-L56)
- [internal/handler/device.go:26-84](file://internal/handler/device.go#L26-L84)
- [internal/repository/brand.go:20-50](file://internal/repository/brand.go#L20-L50)
- [internal/repository/model.go:20-61](file://internal/repository/model.go#L20-L61)
+**图表来源**
+- [internal/router/router.go:32-36](file://internal/router/router.go#L32-L36)
+- [internal/handler/brand.go:29](file://internal/handler/brand.go#L29)
+- [internal/handler/model.go:30](file://internal/handler/model.go#L30)
+- [internal/handler/model_list.go:37](file://internal/handler/model_list.go#L37)
+- [internal/handler/device.go:71](file://internal/handler/device.go#L71)
+- [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/search/meilisearch.go:22-45](file://internal/search/meilisearch.go#L22-L45)

 ## 详细组件分析

 ### 健康检查处理器（HealthHandler）
- 职责：对外暴露健康检查端点，返回统一响应体中的状态字段。
- 接口设计：无状态对象，构造函数仅初始化空实例。
- 实现要点：
+- **职责**：对外暴露健康检查端点，返回统一响应体中的状态字段。
+- **接口设计**：无状态对象，构造函数仅初始化空实例。
+- **实现要点**：
  - 使用统一响应体封装返回值。
  - 适合被反向代理或编排系统定期探测。
- 典型调用路径：/api/v1/health
+- **典型调用路径**：/api/v1/health

-章节来源
+**章节来源**
 - [internal/handler/health.go:8-19](file://internal/handler/health.go#L8-L19)
- [internal/response/response.go:9-37](file://internal/response/response.go#L9-L37)
- [internal/router/router.go:29](file://internal/router/router.go#L29)
+- [internal/response/response.go:15-21](file://internal/response/response.go#L15-L21)
+- [internal/router/router.go:40](file://internal/router/router.go#L40)

 ### 品牌处理器（BrandHandler）
- 职责：根据品牌名称模糊查询品牌列表。
- 输入参数：
+- **职责**：根据品牌名称模糊查询品牌列表。
+- **输入参数**：
  - 查询字符串：brandName（可选）
  - 查询字符串：base64Resp（可选，默认开启）
- 处理流程：
+- **处理流程**：
  - 读取查询参数并解析 base64Resp。
  - 调用仓储层执行数据库查询。
  - 若开启 base64Resp，则对结果进行 JSON 编码后返回字符串；否则直接返回 JSON。
- 错误处理：
+- **错误处理**：
  - 仓储查询失败时记录错误并返回统一内部错误。
  - 编码失败时同样返回统一内部错误。
- 数据模型：Brand
+- **数据模型**：Brand
+- **依赖注入**：通过 NewBrandHandler 构造函数注入 BrandRepository 和 zap.Logger

 ```mermaid
 classDiagram
 class BrandHandler {
-repo : "BrandRepository"
-log : "zap.Logger"
-+GetBrand(c)
+- repo : "BrandRepository"
+- log : "zap.Logger"
+ NewBrandHandler(repo, log) : "BrandHandler"
+ GetBrand(c)
 }
 class BrandRepository {
-db : "sql.DB"
-+List(ctx, brandName) : "[]Brand,error"
+- db : "sql.DB"
+- cache : "BrandCache"
+ NewBrandRepository(db, cache) : "BrandRepository"
+ List(ctx, brandName) : "[]Brand,error"
 }
 class Brand {
-+int id
-+string name
+ ID : "int"
+ Name : "string"
 }
-BrandHandler --> BrandRepository : "依赖"
+BrandHandler --> BrandRepository : "依赖注入"
 BrandRepository --> Brand : "返回"
 ```

-图表来源
- [internal/handler/brand.go:14-50](file://internal/handler/brand.go#L14-L50)
- [internal/repository/brand.go:12-50](file://internal/repository/brand.go#L12-L50)
+**图表来源**
+- [internal/handler/brand.go:13-23](file://internal/handler/brand.go#L13-L23)
+- [internal/handler/brand.go:25-48](file://internal/handler/brand.go#L25-L48)
+- [internal/repository/brand.go:14-21](file://internal/repository/brand.go#L14-L21)
+- [internal/repository/brand.go:23-52](file://internal/repository/brand.go#L23-L52)
 - [internal/model/brand.go:3-7](file://internal/model/brand.go#L3-L7)

-章节来源
- [internal/handler/brand.go:14-50](file://internal/handler/brand.go#L14-L50)
- [internal/repository/brand.go:20-50](file://internal/repository/brand.go#L20-L50)
+**章节来源**
+- [internal/handler/brand.go:13-48](file://internal/handler/brand.go#L13-L48)
+- [internal/repository/brand.go:23-52](file://internal/repository/brand.go#L23-L52)
 - [internal/model/brand.go:3-7](file://internal/model/brand.go#L3-L7)

 ### 型号处理器（ModelHandler）
- 职责：根据品牌或型号关键字查询型号列表。
- 输入参数：
+- **职责**：根据品牌或型号关键字查询型号列表。
+- **输入参数**：
  - 查询字符串：brandName（可选）
  - 查询字符串：modelName（可选）
  - 查询字符串：base64Resp（可选，默认开启）
- 处理流程：
+- **处理流程**：
  - 读取查询参数并解析 base64Resp。
  - 调用仓储层执行数据库查询。
  - 结果处理与品牌处理器一致。
- 错误处理：
+- **错误处理**：
  - 仓储查询失败时记录错误并返回统一内部错误。
  - 编码失败时同样返回统一内部错误。
- 数据模型：Model
+- **数据模型**：Model
+- **依赖注入**：通过 NewModelHandler 构造函数注入 ModelRepository 和 zap.Logger

 ```mermaid
 classDiagram
 class ModelHandler {
-repo : "ModelRepository"
-log : "zap.Logger"
-+GetModel(c)
+- repo : "ModelRepository"
+- log : "zap.Logger"
+ NewModelHandler(repo, log) : "ModelHandler"
+ GetModel(c)
 }
 class ModelRepository {
-db : "sql.DB"
-+List(ctx, brandName, modelName) : "[]Model,error"
+- db : "sql.DB"
+- cache : "ModelCache"
+ NewModelRepository(db, cache) : "ModelRepository"
+ List(ctx, brandName, modelName) : "[]Model,error"
 }
 class Model {
-+int id
-+string brandName
-+string name
-+*string form
-+*string rig
-+*string source
-+*string eqKey
-+time createAt
+ ID : "int"
+ BrandName : "string"
+ Name : "string"
+ Form : "*string"
+ Rig : "*string"
+ Source : "*string"
+ EqKey : "*string"
+ CreateAt : "time.Time"
 }
-ModelHandler --> ModelRepository : "依赖"
+ModelHandler --> ModelRepository : "依赖注入"
 ModelRepository --> Model : "返回"
 ```

-图表来源
- [internal/handler/model.go:14-51](file://internal/handler/model.go#L14-L51)
- [internal/repository/model.go:12-61](file://internal/repository/model.go#L12-L61)
+**图表来源**
+- [internal/handler/model.go:13-23](file://internal/handler/model.go#L13-L23)
+- [internal/handler/model.go:25-49](file://internal/handler/model.go#L25-L49)
+- [internal/repository/model.go:14-21](file://internal/repository/model.go#L14-L21)
+- [internal/repository/model.go:23-79](file://internal/repository/model.go#L23-L79)
 - [internal/model/model.go:5-15](file://internal/model/model.go#L5-L15)

-章节来源
- [internal/handler/model.go:14-51](file://internal/handler/model.go#L14-L51)
- [internal/repository/model.go:20-61](file://internal/repository/model.go#L20-L61)
+**章节来源**
+- [internal/handler/model.go:13-49](file://internal/handler/model.go#L13-L49)
+- [internal/repository/model.go:23-79](file://internal/repository/model.go#L23-L79)
 - [internal/model/model.go:5-15](file://internal/model/model.go#L5-L15)

 ### 型号检索处理器（ModelListHandler）
- 职责：基于 Meilisearch 执行全文检索，返回匹配的型号元数据。
- 输入参数：
+- **职责**：基于 Meilisearch 执行全文检索，返回匹配的型号元数据。
+- **输入参数**：
  - 查询字符串：key（必需）
  - 查询字符串：count（可选，默认 100）
  - 查询字符串：base64Resp（可选，默认开启）
- 处理流程：
+- **处理流程**：
  - 读取查询参数并解析 base64Resp。
  - 限制 count 的最大值以避免过大的返回量。
  - 调用搜索客户端执行检索。
  - 结果处理与前两个处理器一致。
- 错误处理：
+- **错误处理**：
  - 检索失败时记录错误并返回统一内部错误。
  - 编码失败时同样返回统一内部错误。
- 数据模型：map[string]any（由搜索结果解码而来）
+- **数据模型**：map[string]any（由搜索结果解码而来）
+- **依赖注入**：通过 NewModelListHandler 构造函数注入 search.Client 和 zap.Logger

 ```mermaid
 sequenceDiagram
@@ -283,41 +306,42 @@ participant E as "自定义Base64"
 participant R as "统一响应"
 C->>ML : "GET /audio/modelList?key=...&count=..."
 ML->>ML : "解析参数与count限制"
-ML->>S : "SearchWithContext(key, limit, attributes)"
+ML->>S : "ModelList(ctx, key, count)"
 S-->>ML : "hits"
 ML->>E : "可选：EncodeJSON(hits)"
 ML-->>C : "JSON 或 Base64(JSON)"
 ```

-图表来源
+**图表来源**
 - [internal/handler/model_list.go:26-56](file://internal/handler/model_list.go#L26-L56)
 - [internal/search/meilisearch.go:22-45](file://internal/search/meilisearch.go#L22-L45)
 - [pkg/encode/base64.go:35-51](file://pkg/encode/base64.go#L35-L51)
 - [internal/response/response.go:15-36](file://internal/response/response.go#L15-L36)

-章节来源
+**章节来源**
 - [internal/handler/model_list.go:14-57](file://internal/handler/model_list.go#L14-L57)
 - [internal/search/meilisearch.go:22-45](file://internal/search/meilisearch.go#L22-L45)
 - [pkg/encode/base64.go:35-51](file://pkg/encode/base64.go#L35-L51)

 ### 设备上报处理器（DeviceHandler）
- 职责：接收设备上报信息（MAC、型号、版本、来源 IP），写入 Redis Hash。
- 输入参数：
+- **职责**：接收设备上报信息（MAC、型号、版本、来源 IP），写入 Redis Hash。
+- **输入参数**：
  - 查询字符串：mac（必填）
  - 查询字符串：model（必填）
  - 查询字符串：ver（可选）
- 处理流程：
+- **处理流程**：
  - 校验必填参数，若缺失则返回统一错误响应。
  - 组装设备信息结构体（含活跃日期、来源 IP、版本）。
  - 将结构体序列化为 JSON 并写入 Redis Hash。
  - 返回统一成功响应。
- 错误处理：
+- **错误处理**：
  - 参数校验失败返回统一错误。
  - JSON 序列化失败返回统一错误。
  - Redis 写入失败返回统一错误。
- 并发与安全：
+- **并发与安全**：
  - Redis HSet 是原子操作，适合高并发场景。
  - 建议对 MAC 去除空白字符，避免重复键。
+- **依赖注入**：通过 NewDeviceHandler 构造函数注入 redis.Client 和 zap.Logger

 ```mermaid
 flowchart TD
@@ -327,7 +351,7 @@ Validate -- 否 --> RespFail["返回统一错误响应"]
 Validate -- 是 --> BuildInfo["组装设备信息结构体"]
 BuildInfo --> Marshal{"JSON序列化成功？"}
 Marshal -- 否 --> RespFail
-Marshal -- 是 --> HSet["Redis HSet(mac, json)"]
+Marshal -- 是 --> HSet["Redis HSet(ctx, key, mac, json)"]
 HSet --> SetOK{"写入成功？"}
 SetOK -- 否 --> RespFail
 SetOK -- 是 --> RespOK["返回统一成功响应"]
@@ -335,20 +359,102 @@ RespFail --> End(["结束"])
 RespOK --> End
 ```

-图表来源
+**图表来源**
 - [internal/handler/device.go:26-84](file://internal/handler/device.go#L26-L84)

-章节来源
+**章节来源**
 - [internal/handler/device.go:14-85](file://internal/handler/device.go#L14-L85)

+## 依赖注入模式详解
+
+### 依赖注入架构
+所有处理器现在都采用构造函数依赖注入模式，通过 New 函数接收所需的依赖项实例：
+
+```mermaid
+graph LR
+MAIN["main.go<br/>应用启动"] --> ROUTER["router.New()<br/>集中装配依赖"]
+ROUTER --> DB["sql.DB<br/>数据库连接"]
+ROUTER --> RDB["redis.Client<br/>Redis客户端"]
+ROUTER --> SEARCH["search.Client<br/>Meilisearch客户端"]
+ROUTER --> LOG["zap.Logger<br/>日志器"]
+ROUTER --> BRANCACHE["cache.BrandCache<br/>品牌缓存"]
+ROUTER --> MODELCACHE["cache.ModelCache<br/>型号缓存"]
+ROUTER --> BRANDREPO["repository.NewBrandRepository()<br/>品牌仓储"]
+ROUTER --> MODELREPO["repository.NewModelRepository()<br/>型号仓储"]
+ROUTER --> HEALTH["handler.NewHealthHandler()<br/>健康检查处理器"]
+ROUTER --> BRAND["handler.NewBrandHandler()<br/>品牌处理器"]
+ROUTER --> MODEL["handler.NewModelHandler()<br/>型号处理器"]
+ROUTER --> MODELLIST["handler.NewModelListHandler()<br/>型号检索处理器"]
+ROUTER --> DEVICE["handler.NewDeviceHandler()<br/>设备上报处理器"]
+```
+
+**图表来源**
+- [cmd/server/main.go:53-69](file://cmd/server/main.go#L53-L69)
+- [internal/router/router.go:16-36](file://internal/router/router.go#L16-L36)
+
+### 依赖注入优势
+- **测试友好**：可以轻松注入模拟对象进行单元测试
+- **解耦**：处理器不再直接依赖具体实现，只依赖抽象接口
+- **可配置**：运行时可以注入不同的实现
+- **生命周期管理**：依赖项的创建和销毁由路由集中管理
+
+### 仓储层依赖
+BrandRepository 和 ModelRepository 现在接收 Redis 缓存实例作为依赖：
+
+```mermaid
+classDiagram
+class BrandRepository {
+- db : "sql.DB"
+- cache : "BrandCache"
+ NewBrandRepository(db, cache) : "BrandRepository"
+ List(ctx, brandName) : "[]Brand,error"
+ ListFromDB(ctx, brandName) : "[]Brand,error"
+}
+class ModelRepository {
+- db : "sql.DB"
+- cache : "ModelCache"
+ NewModelRepository(db, cache) : "ModelRepository"
+ List(ctx, brandName, modelName) : "[]Model,error"
+ ListAllFromDB(ctx) : "[]Model,error"
+ ListByBrandFromDB(ctx, brandName) : "[]Model,error"
+ ListByModelFromDB(ctx, modelName) : "[]Model,error"
+}
+class BrandCache {
+- rdb : "redis.Client"
+ NewBrandCache(rdb) : "BrandCache"
+ GetAll(ctx) : "[]Brand,error"
+ SetAll(ctx, list) : "error"
+}
+class ModelCache {
+- rdb : "redis.Client"
+ NewModelCache(rdb) : "ModelCache"
+ GetByBrand(ctx, brandName) : "[]Model,error"
+ SetByBrand(ctx, brandName, list) : "error"
+ GetAll(ctx) : "[]Model,error"
+ SetAll(ctx, list) : "error"
+}
+BrandRepository --> BrandCache : "依赖注入"
+ModelRepository --> ModelCache : "依赖注入"
+```
+
+**图表来源**
+- [internal/repository/brand.go:14-21](file://internal/repository/brand.go#L14-L21)
+- [internal/repository/model.go:14-21](file://internal/repository/model.go#L14-L21)
+- [internal/cache/brand_cache.go:18-24](file://internal/cache/brand_cache.go#L18-L24)
+- [internal/cache/model_cache.go:19-25](file://internal/cache/model_cache.go#L19-L25)
+
+**章节来源**
+- [internal/router/router.go:16-36](file://internal/router/router.go#L16-L36)
+- [cmd/server/main.go:53-69](file://cmd/server/main.go#L53-L69)
+
 ## 依赖分析
- 依赖注入模式：
-  - 控制器通过构造函数注入仓储、搜索客户端、Redis 客户端与日志器。
+- **依赖注入模式**：
+  - 所有处理器通过构造函数注入依赖项，包括仓储、搜索客户端、Redis 客户端与日志器。
  - 路由在应用启动时集中装配，保证依赖一次性构建与共享。
- 组件耦合：
+- **组件耦合**：
  - 处理器与仓储之间为单向依赖，职责清晰。
  - 搜索与缓存作为外部服务，通过客户端封装接入。
- 可能的循环依赖：
+- **可能的循环依赖**：
  - 当前结构未见循环导入，符合 Go 包管理最佳实践。

 ```mermaid
@@ -363,6 +469,10 @@ BRAND --> BREPO["repository/brand.go"]
 MODEL --> MREPO["repository/model.go"]
 MODELLIST --> SEARCH["search/meilisearch.go"]
 DEVICE --> REDIS["Redis 客户端"]
+BRAND --> BREPO
+BREPO --> BCACHE["cache/brand_cache.go"]
+MODEL --> MREPO
+MREPO --> MCACHE["cache/model_cache.go"]
 BRAND --> ENCODE["pkg/encode/base64.go"]
 MODEL --> ENCODE
 MODELLIST --> ENCODE
@@ -370,62 +480,70 @@ ALL["各处理器"] --> RESP["internal/response/response.go"]
 ALL --> LOG["zap.Logger"]
 ```

-图表来源
- [cmd/server/main.go:64](file://cmd/server/main.go#L64)
- [internal/router/router.go:21-25](file://internal/router/router.go#L21-L25)
- [internal/handler/brand.go:19-24](file://internal/handler/brand.go#L19-L24)
- [internal/handler/model.go:19-24](file://internal/handler/model.go#L19-L24)
- [internal/handler/model_list.go:19-24](file://internal/handler/model_list.go#L19-L24)
- [internal/handler/device.go:19-24](file://internal/handler/device.go#L19-L24)
- [internal/repository/brand.go:16](file://internal/repository/brand.go#L16)
- [internal/repository/model.go:16](file://internal/repository/model.go#L16)
+**图表来源**
+- [cmd/server/main.go:67-70](file://cmd/server/main.go#L67-L70)
+- [internal/router/router.go:27-36](file://internal/router/router.go#L27-L36)
+- [internal/handler/brand.go:18](file://internal/handler/brand.go#L18)
+- [internal/handler/model.go:18](file://internal/handler/model.go#L18)
+- [internal/handler/model_list.go:19](file://internal/handler/model_list.go#L19)
+- [internal/handler/device.go:19](file://internal/handler/device.go#L19)
+- [internal/repository/brand.go:19](file://internal/repository/brand.go#L19)
+- [internal/repository/model.go:19](file://internal/repository/model.go#L19)
 - [internal/search/meilisearch.go:17](file://internal/search/meilisearch.go#L17)
 - [pkg/encode/base64.go:8](file://pkg/encode/base64.go#L8)
 - [internal/response/response.go:9](file://internal/response/response.go#L9)

-章节来源
- [internal/router/router.go:14-42](file://internal/router/router.go#L14-L42)
- [cmd/server/main.go:22-96](file://cmd/server/main.go#L22-L96)
+**章节来源**
+- [internal/router/router.go:16-52](file://internal/router/router.go#L16-L52)
+- [cmd/server/main.go:25-101](file://cmd/server/main.go#L25-L101)

 ## 性能考虑
- 响应体积优化
+- **响应体积优化**
  - 对于大结果集，优先启用自定义 Base64 响应，减少传输体积与字符转义开销。
  - 检索处理器对 count 进行上限控制，避免超大数据量返回。
- 数据库查询
+- **数据库查询**
  - 品牌与型号查询均使用 ORDER BY 与 LIKE，建议在数据库侧建立合适索引以提升模糊查询性能。
- 搜索与缓存
+  - 仓储层现在支持缓存降级，当缓存不可用时自动回退到数据库查询。
+- **搜索与缓存**
  - Meilisearch 适合全文检索，建议合理设置属性检索范围与分页大小。
  - Redis 写入为单键 HSet，具备良好吞吐能力；建议评估内存占用与持久化策略。
- 中间件与日志
+  - 缓存层现在支持全量缓存和按品牌缓存两种策略，提升查询性能。
+- **中间件与日志**
  - 开启 Recovery、CORS、Logger、RequestID 中间件，有助于可观测性与稳定性；注意日志级别与输出频率对性能的影响。
- 并发安全
+- **并发安全**
  - Redis HSet 为线程安全操作；处理器方法本身无共享可变状态，天然并发安全。
- 最佳实践
+  - 依赖注入模式减少了全局状态，提升了并发安全性。
+- **最佳实践**
  - 在生产环境启用 Release 模式，降低框架开销。
  - 对外部依赖（数据库、搜索、缓存）增加超时与重试策略，提升鲁棒性。
+  - 利用缓存预热机制，在应用启动时加载常用数据到缓存。

 ## 故障排查指南
- 健康检查失败
+- **健康检查失败**
  - 确认路由已正确注册到 /api/v1/health。
  - 查看统一响应体是否返回状态字段。
- 品牌/型号查询异常
+- **品牌/型号查询异常**
  - 检查数据库连接与 SQL 查询逻辑。
-  - 关注日志中“query brand”、“query model”的错误堆栈。
- 型号检索异常
+  - 关注日志中"get brand list failed"、"get model list failed"的错误堆栈。
+  - 验证缓存是否正常工作，检查 Redis 连接状态。
+- **型号检索异常**
  - 检查 Meilisearch 配置与索引可用性。
-  - 关注“meilisearch search”与“decode meilisearch hit”的错误。
- 设备上报异常
+  - 关注"model list search failed"与"decode meilisearch hit"的错误。
+- **设备上报异常**
  - 校验必填参数 mac 与 model 是否传入。
-  - 关注 JSON 序列化与 Redis HSet 的错误日志。
- 统一响应与错误码
+  - 关注"marshal device info failed"与"redis hset failed"的错误日志。
+- **依赖注入相关问题**
+  - 确认所有处理器都通过构造函数正确注入了依赖项。
+  - 检查路由装配顺序，确保依赖项在处理器之前创建。
+- **统一响应与错误码**
  - 使用 internal/response/response.go 提供的 OK/Fail/BadRequest/InternalError 方法，确保错误码与消息格式一致。
- 日志与追踪
+- **日志与追踪**
  - 通过 RequestID 中间件串联一次请求的全链路日志，结合 Logger 中间件定位问题。

-章节来源
+**章节来源**
 - [internal/handler/health.go:14-18](file://internal/handler/health.go#L14-L18)
- [internal/handler/brand.go:31-35](file://internal/handler/brand.go#L31-L35)
- [internal/handler/model.go:32-36](file://internal/handler/model.go#L32-L36)
+- [internal/handler/brand.go:30-34](file://internal/handler/brand.go#L30-L34)
+- [internal/handler/model.go:31-35](file://internal/handler/model.go#L31-L35)
 - [internal/handler/model_list.go:38-42](file://internal/handler/model_list.go#L38-L42)
 - [internal/handler/device.go:61-78](file://internal/handler/device.go#L61-L78)
 - [internal/response/response.go:15-36](file://internal/response/response.go#L15-L36)
@@ -433,25 +551,34 @@ ALL --> LOG["zap.Logger"]
 - [internal/middleware/request_id.go:20-31](file://internal/middleware/request_id.go#L20-L31)

 ## 结论
-本处理器模块遵循清晰的分层与依赖注入原则，通过统一响应体与自定义 Base64 编码实现灵活的输出策略，结合 Gin 中间件与外部服务（数据库、Meilisearch、Redis）形成稳定高效的业务处理链路。建议在生产环境中进一步完善超时与重试、索引优化与缓存策略，持续提升性能与可靠性。
+本处理器模块采用全新的依赖注入模式，通过构造函数注入依赖项，实现了更好的解耦和可测试性。通过统一响应体与自定义 Base64 编码实现灵活的输出策略，结合 Gin 中间件与外部服务（数据库、Meilisearch、Redis）形成稳定高效的业务处理链路。新的架构模式简化了处理器实现，提升了代码质量，建议在生产环境中进一步完善超时与重试、索引优化与缓存策略，持续提升性能与可靠性。

 ## 附录
- 路由与处理器映射
+- **路由与处理器映射**
  - /api/v1/health -> HealthHandler.Check
  - /audio/getBrand -> BrandHandler.GetBrand
  - /audio/getModel -> ModelHandler.GetModel
  - /audio/modelList -> ModelListHandler.ModelList
  - /audio/reportDevInfo -> DeviceHandler.ReportDevInfo
- 常用调用示例（路径引用）
-  - 品牌查询：[internal/handler/brand.go:26](file://internal/handler/brand.go#L26)
-  - 型号查询：[internal/handler/model.go:26](file://internal/handler/model.go#L26)
+- **依赖注入示例**
+  - 品牌处理器：BrandHandler.NewBrandHandler(brandRepo, log)
+  - 型号处理器：ModelHandler.NewModelHandler(modelRepo, log)
+  - 型号检索处理器：ModelListHandler.NewModelListHandler(searchClient, log)
+  - 设备上报处理器：DeviceHandler.NewDeviceHandler(redis, log)
+- **常用调用示例（路径引用）**
+  - 品牌查询：[internal/handler/brand.go:25](file://internal/handler/brand.go#L25)
+  - 型号查询：[internal/handler/model.go:25](file://internal/handler/model.go#L25)
  - 型号检索：[internal/handler/model_list.go:26](file://internal/handler/model_list.go#L26)
  - 设备上报：[internal/handler/device.go:26](file://internal/handler/device.go#L26)
  - 健康检查：[internal/handler/health.go:14](file://internal/handler/health.go#L14)
- 配置与启动
+- **配置与启动**
  - 配置加载与环境变量：[internal/config/config.go:18-64](file://internal/config/config.go#L18-L64)
-  - 服务器启动与优雅关闭：[cmd/server/main.go:22-96](file://cmd/server/main.go#L22-L96)
- 中间件
+  - 服务器启动与优雅关闭：[cmd/server/main.go:25-101](file://cmd/server/main.go#L25-L101)
+- **中间件**
  - CORS：[internal/middleware/cors.go:7-21](file://internal/middleware/cors.go#L7-L21)
  - Logger：[internal/middleware/logger.go:10-45](file://internal/middleware/logger.go#L10-L45)
-  - RequestID：[internal/middleware/request_id.go:20-31](file://internal/middleware/request_id.go#L20-L31)
+  - RequestID：[internal/middleware/request_id.go:20-31](file://internal/middleware/request_id.go#L20-L31)
+- **缓存策略**
+  - 品牌缓存：brand:all 键，30分钟TTL
+  - 型号缓存：model:brand:{brand} 和 model:all 键，30分钟TTL
+  - 启动时预热缓存，提升首次查询性能