feat(impedance): 新增用户耳机阻抗功能模块
- 设计并添加 user_headphone_impedance 表，包含唯一复合索引保证数据完整性 - 实现阻抗上报API接口 /audio/reportImpedance，支持设备上传阻抗数据 - 使用Redis Hash结构缓存阻抗数据，键为 "headphone_impedances" - 新增定时持久化任务，每5分钟从Redis读取数据批量写入数据库 - 对品牌和型号数据进行trim+lower归一化处理，支持数据去重更新 - 优化查询性能，确保mac_addr与品牌型号归一化组合唯一索引生效 - 更新故障排查指南，新增Redis缓存及唯一索引相关问题检查 - 新增阻抗持久化配置开关，允许按需启用该功能
This commit is contained in:
eafonyang
@@ -20,20 +20,26 @@
|
||||
- [internal/handler/model_list.go](file://internal/handler/model_list.go)
|
||||
- [internal/handler/model_csv.go](file://internal/handler/model_csv.go)
|
||||
- [internal/handler/curve.go](file://internal/handler/curve.go)
|
||||
- [internal/handler/impedance.go](file://internal/handler/impedance.go)
|
||||
- [internal/repository/model.go](file://internal/repository/model.go)
|
||||
- [internal/repository/headphone_impedance.go](file://internal/repository/headphone_impedance.go)
|
||||
- [internal/storage/s3.go](file://internal/storage/s3.go)
|
||||
- [internal/task/device_persist.go](file://internal/task/device_persist.go)
|
||||
- [internal/task/impedance_persist.go](file://internal/task/impedance_persist.go)
|
||||
- [internal/task/share_code_persist.go](file://internal/task/share_code_persist.go)
|
||||
- [internal/model/user_headphone_impedance.go](file://internal/model/user_headphone_impedance.go)
|
||||
- [pkg/logger/logger.go](file://pkg/logger/logger.go)
|
||||
- [README.md](file://README.md)
|
||||
- [sql/user_headphone_impedance.sql](file://sql/user_headphone_impedance.sql)
|
||||
</cite>
|
||||
|
||||
## 更新摘要
|
||||
**所做更改**
|
||||
- 新增 S3 存储支持章节，介绍 AWS S3 集成与 CSV 数据读取
|
||||
- 增强缓存控制中间件章节，详细说明 HTTP 缓存策略配置
|
||||
- 改进日志系统章节，更新日志配置与中间件功能
|
||||
- 更新基础设施架构图，反映新增的 S3 组件
|
||||
- 新增 S3 存储与缓存控制中间件的使用示例
|
||||
- 更新配置清单，包含 S3 相关配置项
|
||||
- 新增耳机阻抗数据持久化后台任务系统章节，详细介绍从Redis到数据库的定期数据同步机制
|
||||
- 增强后台任务系统章节，说明设备、分享码和阻抗数据的统一持久化架构
|
||||
- 更新架构图，反映新增的后台任务组件和数据流向
|
||||
- 新增配置选项，支持独立控制阻抗持久化任务的启用状态
|
||||
- 完善错误处理和重试机制说明，确保数据一致性保障
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
@@ -41,22 +47,24 @@
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
6. [后台任务系统](#后台任务系统)
|
||||
7. [依赖分析](#依赖分析)
|
||||
8. [性能考量](#性能考量)
|
||||
9. [故障排除指南](#故障排除指南)
|
||||
10. [结论](#结论)
|
||||
11. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件聚焦于 Luxsin 应用 API 的基础设施组件，系统性阐述缓存系统（Redis）、搜索引擎（Meilisearch）、日志系统（Zap）与新增的 S3 存储系统的配置、初始化流程、连接管理、配置项与运行时行为，并结合实际代码路径说明组件间的协作关系与数据流向。同时提供性能优化建议、监控告警与扩展性设计思路、安全注意事项以及可操作的排障指引。
|
||||
本文件聚焦于 Luxsin 应用 API 的基础设施组件，系统性阐述缓存系统（Redis）、搜索引擎（Meilisearch）、日志系统（Zap）、S3 存储系统与新增的后台任务系统的配置、初始化流程、连接管理、配置项与运行时行为，并结合实际代码路径说明组件间的协作关系与数据流向。同时提供性能优化建议、监控告警与扩展性设计思路、安全注意事项以及可操作的排障指引。
|
||||
|
||||
## 项目结构
|
||||
应用采用分层与按功能模块划分的组织方式：
|
||||
- 入口层：cmd/server/main.go 负责加载配置、初始化日志、数据库、搜索引擎、缓存客户端与 S3 存储，并启动 HTTP 服务。
|
||||
- 配置层：internal/config/* 提供配置加载与校验逻辑，支持从环境变量或默认值读取数据库、Redis、Meilisearch、S3 参数。
|
||||
- 入口层：cmd/server/main.go 负责加载配置、初始化日志、数据库、搜索引擎、缓存客户端、S3 存储与后台任务，并启动 HTTP 服务。
|
||||
- 配置层：internal/config/* 提供配置加载与校验逻辑，支持从环境变量或默认值读取数据库、Redis、Meilisearch、S3 参数及任务开关。
|
||||
- 基础设施接入：internal/database/mysql.go、internal/cache/redis.go、internal/search/meilisearch.go、internal/storage/s3.go 封装底层驱动与 SDK 初始化。
|
||||
- Web 层：internal/router/router.go 注册路由与中间件；internal/middleware/* 提供请求 ID、日志、CORS 与缓存控制中间件。
|
||||
- 业务处理：internal/handler/* 与 internal/repository/* 实现具体业务逻辑。
|
||||
- 后台任务：internal/task/* 提供定时数据持久化任务，实现 Redis 到数据库的异步同步。
|
||||
- 日志封装：pkg/logger/logger.go 提供生产/开发两种日志配置。
|
||||
|
||||
```mermaid
|
||||
@@ -67,10 +75,13 @@ main --> dbinit["internal/database/mysql.go<br/>数据库初始化"]
|
||||
main --> msinit["internal/search/meilisearch.go<br/>搜索引擎初始化"]
|
||||
main --> rdinit["internal/cache/redis.go<br/>缓存初始化"]
|
||||
main --> s3init["internal/storage/s3.go<br/>S3存储初始化"]
|
||||
main --> taskinit["internal/task/*<br/>后台任务初始化"]
|
||||
main --> router["internal/router/router.go<br/>路由与中间件"]
|
||||
router --> cachecontrol["internal/middleware/cache_control.go<br/>缓存控制中间件"]
|
||||
router --> handlers["internal/handler/*<br/>处理器"]
|
||||
handlers --> repos["internal/repository/*<br/>仓储层"]
|
||||
taskinit --> redis["Redis Hash<br/>临时数据存储"]
|
||||
taskinit --> db["MySQL<br/>持久化存储"]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
@@ -86,10 +97,10 @@ handlers --> repos["internal/repository/*<br/>仓储层"]
|
||||
- [internal/router/router.go:22-82](file://internal/router/router.go#L22-L82)
|
||||
|
||||
## 核心组件
|
||||
本节概述四大基础设施组件的职责、初始化与配置要点。
|
||||
本节概述五大基础设施组件的职责、初始化与配置要点。
|
||||
|
||||
- Redis 缓存
|
||||
- 职责：提供键值存储能力，用于热点数据缓存、会话或临时状态存储。
|
||||
- 职责：提供键值存储能力，用于热点数据缓存、会话或临时状态存储，以及后台任务的缓冲队列。
|
||||
- 初始化：在入口处依据配置创建客户端实例，随后在处理器中注入使用。
|
||||
- 关键配置：主机、端口、密码、数据库索引。
|
||||
- 连接管理：入口处创建客户端并在进程退出时关闭；未见显式的连接池参数设置。
|
||||
@@ -111,6 +122,12 @@ handlers --> repos["internal/repository/*<br/>仓储层"]
|
||||
- 关键配置：桶名、区域、访问密钥 ID、秘密访问密钥。
|
||||
- 使用场景：曲线数据读取、CSV 文件存储与访问。
|
||||
|
||||
- 后台任务系统
|
||||
- 职责：提供定时数据持久化能力，将 Redis 中的临时数据异步同步到数据库。
|
||||
- 初始化：根据配置开关启动不同的持久化任务，每个任务独立运行定时器。
|
||||
- 关键配置：ENABLE_PERSIST_TASK、ENABLE_IMPEDANCE_PERSIST_TASK 环境变量。
|
||||
- 数据流：HTTP 请求 -> Redis Hash -> 后台任务 -> 数据库持久化。
|
||||
|
||||
**章节来源**
|
||||
- [internal/cache/redis.go:10-16](file://internal/cache/redis.go#L10-L16)
|
||||
- [internal/config/redis.go:16-56](file://internal/config/redis.go#L16-L56)
|
||||
@@ -120,9 +137,11 @@ handlers --> repos["internal/repository/*<br/>仓储层"]
|
||||
- [internal/middleware/logger.go:10-45](file://internal/middleware/logger.go#L10-L45)
|
||||
- [internal/storage/s3.go:20-39](file://internal/storage/s3.go#L20-L39)
|
||||
- [internal/config/s3.go:12-36](file://internal/config/s3.go#L12-L36)
|
||||
- [internal/task/impedance_persist.go:16-28](file://internal/task/impedance_persist.go#L16-L28)
|
||||
- [internal/config/config.go:19-22](file://internal/config/config.go#L19-L22)
|
||||
|
||||
## 架构总览
|
||||
下图展示应用启动阶段如何初始化四大基础设施，并在运行期如何被业务层调用。
|
||||
下图展示应用启动阶段如何初始化五大基础设施，并在运行期如何被业务层调用。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
@@ -133,6 +152,7 @@ participant DB as "数据库(mysql.go)"
|
||||
participant MS as "搜索引擎(meilisearch.go)"
|
||||
participant RD as "缓存(redis.go)"
|
||||
participant S3 as "S3存储(s3.go)"
|
||||
participant Task as "后台任务(task/*)"
|
||||
participant Router as "路由(router.go)"
|
||||
Entrypoint->>Cfg : 加载配置
|
||||
Entrypoint->>Log : 创建日志实例
|
||||
@@ -140,6 +160,7 @@ Entrypoint->>DB : 初始化数据库连接
|
||||
Entrypoint->>MS : 初始化搜索引擎客户端
|
||||
Entrypoint->>RD : 初始化缓存客户端
|
||||
Entrypoint->>S3 : 初始化S3存储客户端
|
||||
Entrypoint->>Task : 启动持久化任务(条件)
|
||||
Entrypoint->>Router : 注册路由与中间件
|
||||
Router-->>Entrypoint : 返回 HTTP 引擎
|
||||
```
|
||||
@@ -221,14 +242,14 @@ Handler-->>Client : JSON 或 Base64 响应
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [internal/handler/model_list.go:26-67](file://internal/handler/model_list.go#L26-L67)
|
||||
- [internal/search/meilisearch.go:22-45](file://internal/search/meilisearch.go#L22-L45)
|
||||
- [internal/config/meilisearch.go:14-50](file://internal/config/meilisearch.go#L14-L50)
|
||||
- [internal/handler/model_list.go:26-67](file://internal/handler/model_list.go#L26-67)
|
||||
- [internal/search/meilisearch.go:22-45](file://internal/search/meilisearch.go#L22-45)
|
||||
- [internal/config/meilisearch.go:14-50](file://internal/config/meilisearch.go#L14-50)
|
||||
|
||||
**章节来源**
|
||||
- [internal/search/meilisearch.go:17-45](file://internal/search/meilisearch.go#L17-L45)
|
||||
- [internal/handler/model_list.go:26-67](file://internal/handler/model_list.go#L26-L67)
|
||||
- [internal/config/meilisearch.go:14-50](file://internal/config/meilisearch.go#L14-L50)
|
||||
- [internal/search/meilisearch.go:17-45](file://internal/search/meilisearch.go#L17-45)
|
||||
- [internal/handler/model_list.go:26-67](file://internal/handler/model_list.go#L26-67)
|
||||
- [internal/config/meilisearch.go:14-50](file://internal/config/meilisearch.go#L14-50)
|
||||
|
||||
### 日志系统（Zap）
|
||||
- 初始化
|
||||
@@ -255,14 +276,14 @@ LogInfo --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [internal/middleware/request_id.go:20-30](file://internal/middleware/request_id.go#L20-L30)
|
||||
- [internal/middleware/logger.go:10-52](file://internal/middleware/logger.go#L10-L52)
|
||||
- [pkg/logger/logger.go:8-19](file://pkg/logger/logger.go#L8-L19)
|
||||
- [internal/middleware/request_id.go:20-30](file://internal/middleware/request_id.go#L20-30)
|
||||
- [internal/middleware/logger.go:10-52](file://internal/middleware/logger.go#L10-52)
|
||||
- [pkg/logger/logger.go:8-19](file://pkg/logger/logger.go#L8-19)
|
||||
|
||||
**章节来源**
|
||||
- [pkg/logger/logger.go:8-19](file://pkg/logger/logger.go#L8-L19)
|
||||
- [internal/middleware/logger.go:10-52](file://internal/middleware/logger.go#L10-L52)
|
||||
- [internal/middleware/request_id.go:20-30](file://internal/middleware/request_id.go#L20-L30)
|
||||
- [pkg/logger/logger.go:8-19](file://pkg/logger/logger.go#L8-19)
|
||||
- [internal/middleware/logger.go:10-52](file://internal/middleware/logger.go#L10-52)
|
||||
- [internal/middleware/request_id.go:20-30](file://internal/middleware/request_id.go#L20-30)
|
||||
|
||||
### S3 存储组件
|
||||
- 初始化流程
|
||||
@@ -299,14 +320,14 @@ Idle --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [internal/storage/s3.go:20-56](file://internal/storage/s3.go#L20-L56)
|
||||
- [internal/config/s3.go:12-36](file://internal/config/s3.go#L12-L36)
|
||||
- [cmd/server/main.go:100-107](file://cmd/server/main.go#L100-L107)
|
||||
- [internal/storage/s3.go:20-56](file://internal/storage/s3.go#L20-56)
|
||||
- [internal/config/s3.go:12-36](file://internal/config/s3.go#L12-36)
|
||||
- [cmd/server/main.go:100-107](file://cmd/server/main.go#L100-107)
|
||||
|
||||
**章节来源**
|
||||
- [internal/storage/s3.go:20-56](file://internal/storage/s3.go#L20-L56)
|
||||
- [internal/config/s3.go:12-36](file://internal/config/s3.go#L12-L36)
|
||||
- [cmd/server/main.go:100-107](file://cmd/server/main.go#L100-L107)
|
||||
- [internal/storage/s3.go:20-56](file://internal/storage/s3.go#L20-56)
|
||||
- [internal/config/s3.go:12-36](file://internal/config/s3.go#L12-36)
|
||||
- [cmd/server/main.go:100-107](file://cmd/server/main.go#L100-107)
|
||||
|
||||
### 缓存控制中间件
|
||||
- 功能特性
|
||||
@@ -336,12 +357,12 @@ DirectResp --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [internal/middleware/cache_control.go:11-17](file://internal/middleware/cache_control.go#L11-L17)
|
||||
- [internal/router/router.go:65-77](file://internal/router/router.go#L65-L77)
|
||||
- [internal/middleware/cache_control.go:11-17](file://internal/middleware/cache_control.go#L11-17)
|
||||
- [internal/router/router.go:65-77](file://internal/router/router.go#L65-77)
|
||||
|
||||
**章节来源**
|
||||
- [internal/middleware/cache_control.go:5-17](file://internal/middleware/cache_control.go#L5-L17)
|
||||
- [internal/router/router.go:65-77](file://internal/router/router.go#L65-L77)
|
||||
- [internal/middleware/cache_control.go:5-17](file://internal/middleware/cache_control.go#L5-17)
|
||||
- [internal/router/router.go:65-77](file://internal/router/router.go#L65-77)
|
||||
|
||||
### 数据库（MySQL）与缓存/搜索的协作
|
||||
- 数据库连接
|
||||
@@ -367,13 +388,13 @@ Handler->>MS : 全文搜索可选
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [internal/database/mysql.go:14-46](file://internal/database/mysql.go#L14-L46)
|
||||
- [internal/repository/model.go:20-61](file://internal/repository/model.go#L20-L61)
|
||||
- [internal/handler/model_list.go:26-67](file://internal/handler/model_list.go#L26-L67)
|
||||
- [internal/database/mysql.go:14-46](file://internal/database/mysql.go#L14-46)
|
||||
- [internal/repository/model.go:20-61](file://internal/repository/model.go#L20-61)
|
||||
- [internal/handler/model_list.go:26-67](file://internal/handler/model_list.go#L26-67)
|
||||
|
||||
**章节来源**
|
||||
- [internal/database/mysql.go:14-46](file://internal/database/mysql.go#L14-L46)
|
||||
- [internal/repository/model.go:20-61](file://internal/repository/model.go#L20-L61)
|
||||
- [internal/database/mysql.go:14-46](file://internal/database/mysql.go#L14-46)
|
||||
- [internal/repository/model.go:20-61](file://internal/repository/model.go#L20-61)
|
||||
|
||||
### S3 存储与缓存控制中间件的使用示例
|
||||
- CSV 数据读取
|
||||
@@ -389,14 +410,123 @@ Handler->>MS : 全文搜索可选
|
||||
- 确保 Base64 响应的缓存一致性。
|
||||
|
||||
**章节来源**
|
||||
- [internal/handler/model_csv.go:30-102](file://internal/handler/model_csv.go#L30-L102)
|
||||
- [internal/handler/curve.go:491-509](file://internal/handler/curve.go#L491-L509)
|
||||
- [internal/storage/s3.go:41-56](file://internal/storage/s3.go#L41-L56)
|
||||
- [internal/handler/model_csv.go:30-102](file://internal/handler/model_csv.go#L30-102)
|
||||
- [internal/handler/curve.go:491-509](file://internal/handler/curve.go#L491-509)
|
||||
- [internal/storage/s3.go:41-56](file://internal/storage/s3.go#L41-56)
|
||||
|
||||
## 后台任务系统
|
||||
|
||||
### 耳机阻抗数据持久化任务
|
||||
新增的耳机阻抗数据持久化任务实现了从 Redis 到数据库的异步数据同步，确保用户上报的耳机阻抗数据能够可靠地持久化存储。
|
||||
|
||||
- 任务架构
|
||||
- ImpedancePersistTask 结构体包含 Redis 客户端、阻抗仓储和日志器。
|
||||
- 使用 time.Ticker 实现定时执行，默认每 5 分钟执行一次。
|
||||
- 独立的 Redis Key "headphone_impedances" 存储待持久化的阻抗数据。
|
||||
|
||||
- 数据流程
|
||||
- HTTP 请求接收阻抗数据 -> 写入 Redis Hash -> 后台任务定时读取 -> 批量持久化到数据库 -> 成功后删除 Redis 记录。
|
||||
- 每个阻抗记录使用 "mac_addr|brand_norm|model_norm" 作为唯一标识符。
|
||||
- 支持幂等性处理，重复数据不会造成数据库冲突。
|
||||
|
||||
- 错误处理与重试机制
|
||||
- 单个记录持久化失败不影响其他记录的处理。
|
||||
- 失败的记录保留在 Redis 中，下次任务执行时自动重试。
|
||||
- 详细的错误日志记录，包括失败原因和影响范围统计。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Req["阻抗上报请求"] --> Redis["写入 Redis Hash<br/>headphone_impedances"]
|
||||
Redis --> Task["ImpedancePersistTask<br/>定时任务"]
|
||||
Task --> Read["HGetAll 读取所有记录"]
|
||||
Read --> Process["逐条处理记录"]
|
||||
Process --> CheckExist{"数据库中是否存在?"}
|
||||
CheckExist --> |不存在| Insert["INSERT 新记录"]
|
||||
CheckExist --> |已存在| Update["UPDATE 更新记录"]
|
||||
Insert --> Success["标记成功"]
|
||||
Update --> Success
|
||||
Success --> Delete["HDel 删除成功记录"]
|
||||
Delete --> Retry{"是否有失败记录?"}
|
||||
Retry --> |是| Keep["保留失败记录<br/>下次重试"]
|
||||
Retry --> |否| Complete["任务完成"]
|
||||
Keep --> Complete
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [internal/task/impedance_persist.go:44-108](file://internal/task/impedance_persist.go#L44-108)
|
||||
- [internal/handler/impedance.go:92-101](file://internal/handler/impedance.go#L92-101)
|
||||
- [internal/repository/headphone_impedance.go:119-162](file://internal/repository/headphone_impedance.go#L119-162)
|
||||
|
||||
### 统一的后台任务架构
|
||||
系统采用统一的后台任务架构，支持多种数据类型的一致化处理：
|
||||
|
||||
- 设备信息持久化任务 (DevicePersistTask)
|
||||
- 处理设备上报信息，同步到 user_device 和 user_active 表。
|
||||
- 支持版本信息和活跃日期处理。
|
||||
|
||||
- 分享码持久化任务 (ShareCodePersistTask)
|
||||
- 处理分享码的导出和导入日志持久化。
|
||||
- 使用分布式锁防止重复处理。
|
||||
|
||||
- 阻抗数据持久化任务 (ImpedancePersistTask)
|
||||
- 处理耳机阻抗数据的异步持久化。
|
||||
- 支持品牌型号标准化和去重处理。
|
||||
|
||||
- 任务配置管理
|
||||
- ENABLE_PERSIST_TASK：控制设备和分享码任务。
|
||||
- ENABLE_IMPEDANCE_PERSIST_TASK：独立控制阻抗任务。
|
||||
- 所有任务都支持优雅启动和停止。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "后台任务系统"
|
||||
DeviceTask["DevicePersistTask<br/>设备信息持久化"]
|
||||
ShareTask["ShareCodePersistTask<br/>分享码持久化"]
|
||||
ImpedanceTask["ImpedancePersistTask<br/>阻抗数据持久化"]
|
||||
end
|
||||
subgraph "数据源"
|
||||
RedisDevices["Redis Hash: devices"]
|
||||
RedisShare["Redis: 分享码缓存"]
|
||||
RedisImpedance["Redis Hash: headphone_impedances"]
|
||||
end
|
||||
subgraph "数据存储"
|
||||
MySQL["MySQL 数据库"]
|
||||
UserDevice["user_device 表"]
|
||||
UserActive["user_active 表"]
|
||||
ShareLog["share_code_log 表"]
|
||||
UserImpedance["user_headphone_impedance 表"]
|
||||
end
|
||||
DeviceTask --> RedisDevices
|
||||
ShareTask --> RedisShare
|
||||
ImpedanceTask --> RedisImpedance
|
||||
DeviceTask --> UserDevice
|
||||
DeviceTask --> UserActive
|
||||
ShareTask --> ShareLog
|
||||
ImpedanceTask --> UserImpedance
|
||||
UserDevice --> MySQL
|
||||
UserActive --> MySQL
|
||||
ShareLog --> MySQL
|
||||
UserImpedance --> MySQL
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [internal/task/device_persist.go:14-35](file://internal/task/device_persist.go#L14-35)
|
||||
- [internal/task/share_code_persist.go:14-34](file://internal/task/share_code_persist.go#L14-34)
|
||||
- [internal/task/impedance_persist.go:16-41](file://internal/task/impedance_persist.go#L16-41)
|
||||
- [cmd/server/main.go:86-106](file://cmd/server/main.go#L86-106)
|
||||
|
||||
**章节来源**
|
||||
- [internal/task/impedance_persist.go:16-163](file://internal/task/impedance_persist.go#L16-163)
|
||||
- [internal/task/device_persist.go:14-185](file://internal/task/device_persist.go#L14-185)
|
||||
- [internal/task/share_code_persist.go:14-232](file://internal/task/share_code_persist.go#L14-232)
|
||||
- [internal/config/config.go:68-69](file://internal/config/config.go#L68-69)
|
||||
- [cmd/server/main.go:86-106](file://cmd/server/main.go#L86-106)
|
||||
|
||||
## 依赖分析
|
||||
- 组件耦合
|
||||
- 入口层集中初始化四大基础设施并向路由层注入。
|
||||
- 处理器通过依赖注入的方式使用数据库、搜索引擎、缓存客户端与 S3 存储。
|
||||
- 入口层集中初始化五大基础设施并向路由层注入。
|
||||
- 处理器通过依赖注入的方式使用数据库、搜索引擎、缓存客户端、S3 存储和后台任务。
|
||||
- 后台任务系统独立运行，通过 Redis 和数据库间接与其他组件交互。
|
||||
- 外部依赖
|
||||
- Gin：Web 框架与路由。
|
||||
- go-sql-driver/mysql：MySQL 驱动。
|
||||
@@ -415,24 +545,28 @@ Entrypoint --> MySQL["MySQL 驱动"]
|
||||
Entrypoint --> Redis["Redis 客户端"]
|
||||
Entrypoint --> Meili["Meilisearch 客户端"]
|
||||
Entrypoint --> S3["S3 存储"]
|
||||
Entrypoint --> Tasks["后台任务系统"]
|
||||
Gin --> Handlers["处理器"]
|
||||
Handlers --> Repos["仓储"]
|
||||
Handlers --> S3Storage["S3 存储"]
|
||||
Tasks --> Redis
|
||||
Tasks --> MySQL
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [cmd/server/main.go:38-110](file://cmd/server/main.go#L38-L110)
|
||||
- [internal/router/router.go:22-82](file://internal/router/router.go#L22-L82)
|
||||
- [cmd/server/main.go:38-110](file://cmd/server/main.go#L38-110)
|
||||
- [internal/router/router.go:22-82](file://internal/router/router.go#L22-82)
|
||||
|
||||
**章节来源**
|
||||
- [cmd/server/main.go:38-110](file://cmd/server/main.go#L38-L110)
|
||||
- [internal/router/router.go:22-82](file://internal/router/router.go#L22-L82)
|
||||
- [cmd/server/main.go:38-110](file://cmd/server/main.go#L38-110)
|
||||
- [internal/router/router.go:22-82](file://internal/router/router.go#L22-82)
|
||||
|
||||
## 性能考量
|
||||
- Redis
|
||||
- 建议增加连接池参数配置（最大空闲/活动连接、超时），以提升高并发下的稳定性与吞吐。
|
||||
- 对热点键设置合理的过期策略，避免内存膨胀。
|
||||
- 使用 pipeline 或批量操作降低 RTT。
|
||||
- 后台任务批量处理可减少数据库压力。
|
||||
- Meilisearch
|
||||
- 控制返回字段与数量，减少序列化与传输开销。
|
||||
- 对高频查询建立索引与排序规则，优化查询性能。
|
||||
@@ -440,6 +574,7 @@ Handlers --> S3Storage["S3 存储"]
|
||||
- 日志
|
||||
- 生产环境建议异步落盘或使用缓冲队列，避免阻塞请求。
|
||||
- 控制日志字段数量，避免过度编码。
|
||||
- 后台任务日志应关注批处理统计信息。
|
||||
- S3 存储
|
||||
- 配置适当的连接超时与重试策略，避免长时间阻塞。
|
||||
- 对频繁访问的 CSV 文件考虑在应用层增加缓存。
|
||||
@@ -448,6 +583,10 @@ Handlers --> S3Storage["S3 存储"]
|
||||
- 根据内容特性和访问模式选择合适的缓存策略。
|
||||
- 定期监控缓存命中率，调整缓存时间和策略。
|
||||
- 注意 Base64 响应的缓存一致性问题。
|
||||
- 后台任务
|
||||
- 合理设置任务执行间隔，平衡实时性与性能。
|
||||
- 监控任务执行时间和成功率。
|
||||
- 考虑任务失败时的告警机制。
|
||||
|
||||
## 故障排除指南
|
||||
- Redis
|
||||
@@ -469,16 +608,21 @@ Handlers --> S3Storage["S3 存储"]
|
||||
- 症状：缓存策略不生效或缓存污染。
|
||||
- 排查：检查中间件应用顺序；验证 Cache-Control 头部设置；确认 Vary 头部配置。
|
||||
- 建议：使用浏览器开发者工具检查响应头，确保缓存策略正确应用。
|
||||
- 后台任务
|
||||
- 症状：数据未持久化或持久化失败。
|
||||
- 排查：检查任务开关配置；查看任务日志中的错误信息；确认 Redis 和数据库连接正常。
|
||||
- 建议：监控任务执行状态，设置失败告警；定期检查 Redis 中积压的数据量。
|
||||
|
||||
**章节来源**
|
||||
- [internal/config/redis.go:51-56](file://internal/config/redis.go#L51-L56)
|
||||
- [internal/config/meilisearch.go:39-50](file://internal/config/meilisearch.go#L39-L50)
|
||||
- [internal/database/mysql.go:33-35](file://internal/database/mysql.go#L33-L35)
|
||||
- [internal/storage/s3.go:41-56](file://internal/storage/s3.go#L41-L56)
|
||||
- [internal/middleware/cache_control.go:5-17](file://internal/middleware/cache_control.go#L5-L17)
|
||||
- [internal/config/redis.go:51-56](file://internal/config/redis.go#L51-56)
|
||||
- [internal/config/meilisearch.go:39-50](file://internal/config/meilisearch.go#L39-50)
|
||||
- [internal/database/mysql.go:33-35](file://internal/database/mysql.go#L33-35)
|
||||
- [internal/storage/s3.go:41-56](file://internal/storage/s3.go#L41-56)
|
||||
- [internal/middleware/cache_control.go:5-17](file://internal/middleware/cache_control.go#L5-17)
|
||||
- [internal/task/impedance_persist.go:48-50](file://internal/task/impedance_persist.go#L48-50)
|
||||
|
||||
## 结论
|
||||
本项目在基础设施层面实现了清晰的分层与职责分离：入口集中初始化、配置统一加载、日志结构化输出、数据库与搜索引擎按需接入、S3 存储支持。当前代码已具备可扩展的基础，建议在 Redis 与搜索层面补充连接池与缓存策略，在日志层面增强异步与采样能力，并完善监控与告警体系以支撑生产环境的稳定性与可观测性。新增的 S3 存储为频响数据提供了可靠的云端存储解决方案，配合缓存控制中间件可以有效提升用户体验。
|
||||
本项目在基础设施层面实现了清晰的分层与职责分离：入口集中初始化、配置统一加载、日志结构化输出、数据库与搜索引擎按需接入、S3 存储支持，以及新增的后台任务系统。当前代码已具备可扩展的基础，建议在 Redis 与搜索层面补充连接池与缓存策略，在日志层面增强异步与采样能力，并完善监控与告警体系以支撑生产环境的稳定性与可观测性。新增的 S3 存储为频响数据提供了可靠的云端存储解决方案，配合缓存控制中间件可以有效提升用户体验。后台任务系统实现了从 Redis 到数据库的可靠数据同步，确保了数据的最终一致性。
|
||||
|
||||
## 附录
|
||||
|
||||
@@ -496,13 +640,19 @@ Handlers --> S3Storage["S3 存储"]
|
||||
- S3 配置
|
||||
- 支持通过 S3_BUCKET/AWS_REGION/AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY 覆盖默认值。
|
||||
- 开发环境可使用静态凭证，生产环境建议使用 IAM 角色或环境变量。
|
||||
- 后台任务配置
|
||||
- ENABLE_PERSIST_TASK：启用设备和分享码持久化任务。
|
||||
- ENABLE_IMPEDANCE_PERSIST_TASK：启用阻抗数据持久化任务。
|
||||
- SHARE_CODE_TTL_MIN：分享码 TTL 最小值（分钟）。
|
||||
- SHARE_CODE_MAX_PER_MAC：每个 MAC 地址的最大分享码数量。
|
||||
|
||||
**章节来源**
|
||||
- [README.md:39-73](file://README.md#L39-L73)
|
||||
- [internal/config/database.go:17-55](file://internal/config/database.go#L17-L55)
|
||||
- [internal/config/redis.go:16-48](file://internal/config/redis.go#L16-L48)
|
||||
- [internal/config/meilisearch.go:14-36](file://internal/config/meilisearch.go#L14-L36)
|
||||
- [internal/config/s3.go:12-36](file://internal/config/s3.go#L12-L36)
|
||||
- [internal/config/redis.go:16-48](file://internal/config/redis.go#L16-48)
|
||||
- [internal/config/meilisearch.go:14-36](file://internal/config/meilisearch.go#L14-36)
|
||||
- [internal/config/s3.go:12-36](file://internal/config/s3.go#L12-36)
|
||||
- [internal/config/config.go:68-72](file://internal/config/config.go#L68-72)
|
||||
|
||||
### 最佳实践
|
||||
- 安全
|
||||
@@ -513,10 +663,12 @@ Handlers --> S3Storage["S3 存储"]
|
||||
- 为 Redis、数据库、搜索引擎与 S3 增加健康检查与熔断策略。
|
||||
- 对外部依赖调用增加超时与重试。
|
||||
- S3 操作增加重试机制和错误处理。
|
||||
- 后台任务增加失败重试和告警机制。
|
||||
- 可观测性
|
||||
- 结合请求 ID 串联日志、指标与链路追踪。
|
||||
- 对关键路径埋点，关注延迟分布与错误率。
|
||||
- 监控 S3 存储的访问模式和成本。
|
||||
- 监控后台任务的执行状态和数据同步情况。
|
||||
- 缓存策略
|
||||
- 根据内容特性和访问模式选择合适的缓存策略。
|
||||
- 定期监控缓存命中率，调整缓存时间和策略。
|
||||
@@ -533,10 +685,15 @@ Handlers --> S3Storage["S3 存储"]
|
||||
- 日志与监控
|
||||
- 增加指标采集（QPS、P95/P99、错误率）与告警阈值。
|
||||
- 使用分布式追踪定位慢调用。
|
||||
- 监控后台任务的执行性能和成功率。
|
||||
- 存储层
|
||||
- 考虑引入 CDN 加速静态资源访问。
|
||||
- 对 S3 存储增加版本控制和生命周期管理。
|
||||
- 实现存储成本优化策略。
|
||||
- 后台任务
|
||||
- 支持任务优先级和调度策略。
|
||||
- 实现任务失败的重试和补偿机制。
|
||||
- 添加任务执行的监控和告警。
|
||||
|
||||
### S3 存储使用示例
|
||||
- CSV 数据读取
|
||||
@@ -549,6 +706,16 @@ Handlers --> S3Storage["S3 存储"]
|
||||
- 实现 CSV 数据的缓存与复用。
|
||||
|
||||
**章节来源**
|
||||
- [internal/handler/model_csv.go:30-102](file://internal/handler/model_csv.go#L30-L102)
|
||||
- [internal/handler/curve.go:491-509](file://internal/handler/curve.go#L491-L509)
|
||||
- [internal/storage/s3.go:41-56](file://internal/storage/s3.go#L41-L56)
|
||||
- [internal/handler/model_csv.go:30-102](file://internal/handler/model_csv.go#L30-102)
|
||||
- [internal/handler/curve.go:491-509](file://internal/handler/curve.go#L491-509)
|
||||
- [internal/storage/s3.go:41-56](file://internal/storage/s3.go#L41-56)
|
||||
|
||||
### 数据库表结构
|
||||
- 用户耳机阻抗表 (user_headphone_impedance)
|
||||
- 主键：id (自增)
|
||||
- 唯一索引：uniq_mac_brand_model (mac_addr, headphone_brand_norm, headphone_model_norm)
|
||||
- 普通索引：idx_mac, idx_device_model
|
||||
- 字段包括：设备MAC地址、设备型号、阻抗值、耳机品牌信息、IP地址、时间戳等。
|
||||
|
||||
**章节来源**
|
||||
- [sql/user_headphone_impedance.sql:20-36](file://sql/user_headphone_impedance.sql#L20-36)
|
||||
Reference in New Issue
Block a user