audio/app-api
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7687e6a0d94a08f0e7ff6b7497dd632844e3790d
app-api/.qoder/repowiki/zh/content/核心模块/业务处理器.md
T
yangy 665397ede7 feat(ota): 增强设备管理与OTA功能模块 
- 新增OTA固件升级处理器，支持固件升级请求及黑名单过滤
- 引入设备持久化仓储，支持设备信息上报与活动记录
- 扩展数据模型，新增UserDevice与UserActive，支持设备版本跟踪
- 实现Redis到MySQL的异步数据同步任务
- 更新路由配置，集成新的API端点以支持OTA功能
- 优化架构图，反映新增的数据流与处理流程
2026-05-31 09:52:11 +08:00

33 KiB
Raw Blame History

业务处理器

**本文引用的文件** - [internal/handler/brand.go](file://internal/handler/brand.go) - [internal/handler/model.go](file://internal/handler/model.go) - [internal/handler/model_list.go](file://internal/handler/model_list.go) - [internal/handler/device.go](file://internal/handler/device.go) - [internal/handler/health.go](file://internal/handler/health.go) - [internal/handler/ota.go](file://internal/handler/ota.go) - [internal/repository/brand.go](file://internal/repository/brand.go) - [internal/repository/model.go](file://internal/repository/model.go) - [internal/repository/ota.go](file://internal/repository/ota.go) - [internal/response/response.go](file://internal/response/response.go) - [pkg/encode/base64.go](file://pkg/encode/base64.go) - [internal/search/meilisearch.go](file://internal/search/meilisearch.go) - [internal/router/router.go](file://internal/router/router.go) - [cmd/server/main.go](file://cmd/server/main.go) - [internal/config/config.go](file://internal/config/config.go) - [internal/middleware/logger.go](file://internal/middleware/logger.go) - [internal/middleware/cors.go](file://internal/middleware/cors.go) - [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/model/ota.go](file://internal/model/ota.go) - [internal/cache/brand_cache.go](file://internal/cache/brand_cache.go) - [internal/cache/model_cache.go](file://internal/cache/model_cache.go) - [sql/ota.sql](file://sql/ota.sql) - [sql/black_list.sql](file://sql/black_list.sql) - [sql/ota_target_device.sql](file://sql/ota_target_device.sql)

更新摘要

变更内容

  • 新增OTA固件升级处理功能：引入OTAHandler组件，支持固件升级请求处理、黑名单过滤、目标设备分布和版本选择等OTA固件升级能力
  • 新增OTA仓储层：OTARepository提供完整的OTA数据访问能力，包括最新版本查询、黑名单检查、定向设备匹配等功能
  • 新增OTA数据模型：包含OTA、BlackList、OTATargetDevice三种数据结构，支持完整的OTA升级流程
  • 新增数据库表结构：ota、black_list、ota_target_device三张表，支撑OTA功能的数据存储需求
  • 更新路由集成：OTA功能已集成到/audio路由组中，提供/api/v1/audio/ota端点

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖注入模式详解
  7. 依赖分析
  8. 性能考虑
  9. 故障排查指南
  10. 结论
  11. 附录

简介

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

项目结构

业务处理器位于 internal/handler 目录，采用依赖注入模式，围绕"控制器-仓储-搜索-缓存-响应"的分层组织，配合中间件与路由装配，形成清晰的控制流与依赖注入入口。新增的OTA功能通过独立的处理器、仓储层和数据模型实现完整的固件升级能力。

graph TB
subgraph "应用入口"
MAIN["cmd/server/main.go<br/>启动与配置加载"]
END
subgraph "路由与中间件"
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<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)"]
OTA["internal/handler/ota.go<br/>NewOTAHandler(otaRepo, log)"]
end
subgraph "仓储层"
BRANDREPO["internal/repository/brand.go<br/>BrandRepository"]
MODELREPO["internal/repository/model.go<br/>ModelRepository"]
OTAREPO["internal/repository/ota.go<br/>OTARepository"]
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缓存"]
DB["MySQL 数据库<br/>ota, black_list, ota_target_device 表"]
end
MAIN --> ROUTER
ROUTER --> CORS
ROUTER --> LOGMW
ROUTER --> REQID
ROUTER --> HEALTH
ROUTER --> BRAND
ROUTER --> MODEL
ROUTER --> MODELLIST
ROUTER --> DEVICE
ROUTER --> OTA
BRAND --> BRANDREPO
MODEL --> MODELREPO
OTA --> OTAREPO
BRANDREPO --> DB
MODELREPO --> DB
OTAREPO --> DB
BRAND --> RESP
MODEL --> RESP
MODELLIST --> RESP
DEVICE --> RESP
OTA --> RESP
MODELLIST --> SEARCH
BRAND --> CACHE
MODEL --> CACHE
BRAND --> ENCODE
MODEL --> ENCODE
MODELLIST --> ENCODE

图表来源

章节来源

核心组件

  • 健康检查处理器：提供轻量级健康状态返回，便于外部探活与编排。
  • 品牌查询处理器：按品牌名模糊查询品牌列表，现在依赖 BrandRepository 实例。
  • 型号查询处理器：按品牌或型号关键字查询型号列表，现在依赖 ModelRepository 实例。
  • 型号检索处理器：基于 Meilisearch 执行全文检索，依赖搜索客户端实例。
  • 设备上报处理器：接收设备信息（MAC、型号、版本、来源 IP），依赖 Redis 客户端。
  • OTA固件升级处理器：处理固件升级请求，支持黑名单过滤、目标设备分布和版本选择等OTA固件升级能力。

章节来源

架构总览

下图展示从请求进入至响应返回的关键路径，以及处理器与仓储、搜索、缓存、日志等组件的交互，体现了完整的依赖注入架构。新增的OTA功能通过独立的处理流程支持复杂的固件升级场景。

sequenceDiagram
participant C as "客户端"
participant R as "Gin 路由"
participant H as "业务处理器"
participant REPO as "仓储层"
participant DB as "MySQL数据库"
participant L as "Zap 日志"
C->>R : "HTTP 请求"
R->>H : "匹配到处理器并调用"
alt "品牌/型号查询"
H->>REPO : "List(ctx, filters)"
REPO-->>H : "结果集"
else "型号检索"
H->>DB : "Meilisearch查询"
DB-->>H : "命中结果"
else "设备上报"
H->>DB : "Redis HSet(ctx, key, mac, json)"
DB-->>H : "OK 或错误"
else "OTA固件升级"
H->>REPO : "GetLatestOTA(ctx, model, hw, beta)"
REPO->>DB : "查询最新OTA记录"
DB-->>REPO : "OTA记录"
REPO-->>H : "OTA记录"
H->>REPO : "IsInBlackList(ctx, otaID, mac)"
REPO->>DB : "检查黑名单"
DB-->>REPO : "命中/未命中"
H->>REPO : "FindTargetDevice(ctx, otaID, mac)"
REPO->>DB : "检查定向设备"
DB-->>REPO : "匹配/不匹配"
end
H->>L : "记录日志/错误"
H-->>C : "JSON 响应"

图表来源

详细组件分析

健康检查处理器（HealthHandler）

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

章节来源

品牌处理器（BrandHandler）

  • 职责：根据品牌名称模糊查询品牌列表。
  • 输入参数：
    • 查询字符串：brandName（可选）
    • 查询字符串：base64Resp（可选，默认开启）
  • 处理流程：
    • 读取查询参数并解析 base64Resp。
    • 调用仓储层执行数据库查询。
    • 若开启 base64Resp，则对结果进行 JSON 编码后返回字符串；否则直接返回 JSON。
  • 错误处理：
    • 仓储查询失败时记录错误并返回统一内部错误。
    • 编码失败时同样返回统一内部错误。
  • 数据模型：Brand
  • 依赖注入：通过 NewBrandHandler 构造函数注入 BrandRepository 和 zap.Logger
classDiagram
class BrandHandler {
- repo : "BrandRepository"
- log : "zap.Logger"
+ NewBrandHandler(repo, log) : "BrandHandler"
+ GetBrand(c)
}
class BrandRepository {
- db : "sql.DB"
- cache : "BrandCache"
+ NewBrandRepository(db, cache) : "BrandRepository"
+ List(ctx, brandName) : "[]Brand,error"
}
class Brand {
+ ID : "int"
+ Name : "string"
}
BrandHandler --> BrandRepository : "依赖注入"
BrandRepository --> Brand : "返回"

图表来源

章节来源

型号处理器（ModelHandler）

  • 职责：根据品牌或型号关键字查询型号列表。
  • 输入参数：
    • 查询字符串：brandName（可选）
    • 查询字符串：modelName（可选）
    • 查询字符串：base64Resp（可选，默认开启）
  • 处理流程：
    • 读取查询参数并解析 base64Resp。
    • 调用仓储层执行数据库查询。
    • 结果处理与品牌处理器一致。
  • 错误处理：
    • 仓储查询失败时记录错误并返回统一内部错误。
    • 编码失败时同样返回统一内部错误。
  • 数据模型：Model
  • 依赖注入：通过 NewModelHandler 构造函数注入 ModelRepository 和 zap.Logger
classDiagram
class ModelHandler {
- repo : "ModelRepository"
- log : "zap.Logger"
+ NewModelHandler(repo, log) : "ModelHandler"
+ GetModel(c)
}
class ModelRepository {
- db : "sql.DB"
- cache : "ModelCache"
+ NewModelRepository(db, cache) : "ModelRepository"
+ List(ctx, brandName, modelName) : "[]Model,error"
}
class Model {
+ ID : "int"
+ BrandName : "string"
+ Name : "string"
+ Form : "*string"
+ Rig : "*string"
+ Source : "*string"
+ EqKey : "*string"
+ CreateAt : "time.Time"
}
ModelHandler --> ModelRepository : "依赖注入"
ModelRepository --> Model : "返回"

图表来源

章节来源

型号检索处理器（ModelListHandler）

  • 职责：基于 Meilisearch 执行全文检索，返回匹配的型号元数据。
  • 输入参数：
    • 查询字符串：key（必需）
    • 查询字符串：count（可选，默认 100）
    • 查询字符串：base64Resp（可选，默认开启）
  • 处理流程：
    • 读取查询参数并解析 base64Resp。
    • 限制 count 的最大值以避免过大的返回量。
    • 调用搜索客户端执行检索。
    • 结果处理与前两个处理器一致。
  • 错误处理：
    • 检索失败时记录错误并返回统一内部错误。
    • 编码失败时同样返回统一内部错误。
  • 数据模型：map[string]any（由搜索结果解码而来）
  • 依赖注入：通过 NewModelListHandler 构造函数注入 search.Client 和 zap.Logger
sequenceDiagram
participant C as "客户端"
participant ML as "ModelListHandler"
participant S as "Meilisearch 客户端"
participant E as "自定义Base64"
participant R as "统一响应"
C->>ML : "GET /audio/modelList?key=...&count=..."
ML->>ML : "解析参数与count限制"
ML->>S : "ModelList(ctx, key, count)"
S-->>ML : "hits"
ML->>E : "可选：EncodeJSON(hits)"
ML-->>C : "JSON 或 Base64(JSON)"

图表来源

章节来源

设备上报处理器（DeviceHandler）

  • 职责：接收设备上报信息（MAC、型号、版本、来源 IP），写入 Redis Hash。
  • 输入参数：
    • 查询字符串：mac（必填）
    • 查询字符串：model（必填）
    • 查询字符串：ver（可选）
  • 处理流程：
    • 校验必填参数，若缺失则返回统一错误响应。
    • 组装设备信息结构体（含活跃日期、来源 IP、版本）。
    • 将结构体序列化为 JSON 并写入 Redis Hash。
    • 返回统一成功响应。
  • 错误处理：
    • 参数校验失败返回统一错误。
    • JSON 序列化失败返回统一错误。
    • Redis 写入失败返回统一错误。
  • 并发与安全：
    • Redis HSet 是原子操作，适合高并发场景。
    • 建议对 MAC 去除空白字符，避免重复键。
  • 依赖注入：通过 NewDeviceHandler 构造函数注入 redis.Client 和 zap.Logger
flowchart TD
Start(["进入 ReportDevInfo"]) --> ReadParams["读取参数 mac/model/ver/X-Forwarded-For"]
ReadParams --> Validate{"参数校验通过？"}
Validate -- 否 --> RespFail["返回统一错误响应"]
Validate -- 是 --> BuildInfo["组装设备信息结构体"]
BuildInfo --> Marshal{"JSON序列化成功？"}
Marshal -- 否 --> RespFail
Marshal -- 是 --> HSet["Redis HSet(ctx, key, mac, json)"]
HSet --> SetOK{"写入成功？"}
SetOK -- 否 --> RespFail
SetOK -- 是 --> RespOK["返回统一成功响应"]
RespFail --> End(["结束"])
RespOK --> End

图表来源

章节来源

OTA固件升级处理器（OTAHandler）

  • 职责：处理固件升级请求，支持黑名单过滤、目标设备分布和版本选择等OTA固件升级能力。
  • 输入参数：
    • 查询字符串：model（必填）
    • 查询字符串：hw（必填）
    • 查询字符串：mac（可选）
    • 查询字符串：beta（可选，默认0）
  • 处理流程：
    1. 参数校验：验证model和hw参数，解析beta参数
    2. 查询最新OTA记录：按model+hw+beta+status=1查询最新一条OTA记录
    3. 黑名单检查：检查mac是否在指定ota_id的黑名单中
    4. 定向升级检查：如果是定向升级，检查mac是否在定向设备列表中
    5. 版本选择：根据检查结果返回合适的OTA版本
  • 错误处理：
    • 参数校验失败返回统一错误
    • 数据库查询失败记录错误并返回统一内部错误
    • 黑名单或定向设备检查失败返回统一内部错误
  • 数据模型：OTA、BlackList、OTATargetDevice
  • 依赖注入：通过 NewOTAHandler 构造函数注入 OTARepository 和 zap.Logger
flowchart TD
Start(["进入 GetOTA"]) --> ParseParams["解析参数 model/hw/mac/beta"]
ParseParams --> Validate{"参数校验通过？"}
Validate -- 否 --> RespBadReq["返回BadRequest错误"]
Validate -- 是 --> QueryLatest["查询最新OTA记录"]
QueryLatest --> QueryOK{"查询成功？"}
QueryOK -- 否 --> RespInternal["返回InternalError"]
QueryOK -- 是 --> CheckBlackList["检查黑名单"]
CheckBlackList --> InBlackList{"命中黑名单？"}
InBlackList -- 是 --> QueryNotInBlack["查询不在黑名单中的最新OTA"]
QueryNotInBlack --> BlackListOK{"查询成功？"}
BlackListOK -- 否 --> RespInternal
BlackListOK -- 是 --> ReturnOTA["返回OTA记录"]
InBlackList -- 否 --> CheckTarget{"是否定向升级？"}
CheckTarget -- 否 --> ReturnOTA
CheckTarget -- 是 --> CheckTargetDevice["检查定向设备"]
CheckTargetDevice --> TargetHit{"定向命中？"}
TargetHit -- 是 --> ReturnOTA
TargetHit -- 否 --> QueryNotTarget["查询非定向最新OTA"]
QueryNotTarget --> NotTargetOK{"查询成功？"}
NotTargetOK -- 否 --> RespInternal
NotTargetOK -- 是 --> ReturnOTA
ReturnOTA --> End(["结束"])
RespBadReq --> End
RespInternal --> End

图表来源

章节来源

依赖注入模式详解

依赖注入架构

所有处理器现在都采用构造函数依赖注入模式，通过 New 函数接收所需的依赖项实例：

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 --> OTAREPO["repository.NewOTARepository()<br/>OTA仓储"]
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/>设备上报处理器"]
ROUTER --> OTA["handler.NewOTAHandler()<br/>OTA固件升级处理器"]

图表来源

依赖注入优势

  • 测试友好：可以轻松注入模拟对象进行单元测试
  • 解耦：处理器不再直接依赖具体实现，只依赖抽象接口
  • 可配置：运行时可以注入不同的实现
  • 生命周期管理：依赖项的创建和销毁由路由集中管理

仓储层依赖

BrandRepository、ModelRepository 和 OTARepository 现在接收相应的依赖：

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 OTARepository {
- db : "sql.DB"
+ NewOTARepository(db) : "OTARepository"
+ GetLatestOTA(ctx, modelVal, hw, beta) : "OTA,error"
+ GetLatestOTANotInBlackList(ctx, modelVal, hw, beta, mac) : "OTA,error"
+ GetLatestOTANotTarget(ctx, modelVal, hw, beta) : "OTA,error"
+ IsInBlackList(ctx, otaID, mac) : "bool,error"
+ FindTargetDevice(ctx, otaID, mac) : "OTATargetDevice,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 : "依赖注入"
OTARepository --> DB : "依赖注入"

图表来源

章节来源

依赖分析

  • 依赖注入模式：
    • 所有处理器通过构造函数注入依赖项，包括仓储、搜索客户端、Redis 客户端与日志器。
    • 路由在应用启动时集中装配，保证依赖一次性构建与共享。
  • 组件耦合：
    • 处理器与仓储之间为单向依赖，职责清晰。
    • 搜索与缓存作为外部服务，通过客户端封装接入。
    • OTA处理器与数据库直接交互，提供完整的OTA数据访问能力。
  • 可能的循环依赖：
    • 当前结构未见循环导入，符合 Go 包管理最佳实践。
graph LR
MAIN["main.go"] --> ROUTER["router.go"]
ROUTER --> HEALTH["health.go"]
ROUTER --> BRAND["brand.go"]
ROUTER --> MODEL["model.go"]
ROUTER --> MODELLIST["model_list.go"]
ROUTER --> DEVICE["device.go"]
ROUTER --> OTA["ota.go"]
BRAND --> BREPO["repository/brand.go"]
MODEL --> MREPO["repository/model.go"]
OTA --> OTAREPO["repository/ota.go"]
BRAND --> BREPO
BREPO --> BCACHE["cache/brand_cache.go"]
MODEL --> MREPO
MREPO --> MCACHE["cache/model_cache.go"]
OTA --> OTAREPO
OTAREPO --> DB["MySQL数据库"]
BRAND --> ENCODE["pkg/encode/base64.go"]
MODEL --> ENCODE
MODELLIST --> ENCODE
OTA --> ENCODE
ALL["各处理器"] --> RESP["internal/response/response.go"]
ALL --> LOG["zap.Logger"]

图表来源

章节来源

性能考虑

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

故障排查指南

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

章节来源

结论

本处理器模块采用全新的依赖注入模式，通过构造函数注入依赖项，实现了更好的解耦和可测试性。通过统一响应体与自定义 Base64 编码实现灵活的输出策略，结合 Gin 中间件与外部服务（数据库、Meilisearch、Redis）形成稳定高效的业务处理链路。新增的OTA固件升级功能提供了完整的固件升级能力，包括黑名单过滤、目标设备分布和版本选择等特性。新的架构模式简化了处理器实现，提升了代码质量，建议在生产环境中进一步完善超时与重试、索引优化与缓存策略，持续提升性能与可靠性。

附录

  • 路由与处理器映射
    • /api/v1/health -> HealthHandler.Check
    • /audio/getBrand -> BrandHandler.GetBrand
    • /audio/getModel -> ModelHandler.GetModel
    • /audio/modelList -> ModelListHandler.ModelList
    • /audio/reportDevInfo -> DeviceHandler.ReportDevInfo
    • /audio/ota -> OTAHandler.GetOTA
  • 依赖注入示例
    • 品牌处理器：BrandHandler.NewBrandHandler(brandRepo, log)
    • 型号处理器：ModelHandler.NewModelHandler(modelRepo, log)
    • 型号检索处理器：ModelListHandler.NewModelListHandler(searchClient, log)
    • 设备上报处理器：DeviceHandler.NewDeviceHandler(redis, log)
    • OTA固件升级处理器：OTAHandler.NewOTAHandler(otaRepo, log)
  • OTA查询参数说明
    • model：设备型号（必填）
    • hw：硬件版本号（必填）
    • mac：设备MAC地址（可选）
    • beta：灰度标识（可选，默认0）
  • OTA数据模型字段
    • OTA：id、verCode、verName、url、md5、force、desc、model、hw、target、beta、pawVerCode、pawVerName、pawUrl、pawMd5、startTime、endTime、status
    • BlackList：id、ota_id、mac、create_at
    • OTATargetDevice：id、ota_id、mac_addr、type、create_at
  • 数据库表结构
    • ota表：存储OTA固件升级记录
    • black_list表：存储OTA黑名单
    • ota_target_device表：存储OTA定向设备
  • 常用调用示例（路径引用）
  • 配置与启动
  • 中间件
  • 缓存策略
    • 品牌缓存：brand:all 键，30分钟TTL
    • 型号缓存：model:brand:{brand} 和 model:all 键，30分钟TTL
    • 启动时预热缓存，提升首次查询性能
  • OTA查询流程
    • 最新OTA查询：按model+hw+beta+status=1排序取第一条
    • 黑名单检查：检查mac是否在指定ota_id的黑名单中
    • 定向设备检查：检查mac是否在指定ota_id的定向设备列表中
    • 版本选择：根据检查结果返回合适的OTA版本
Reference in New Issue View Git Blame Copy Permalink