audio/app-api
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0aad0f9c1d2a78421ebac23ff7f432bb2c92aa29
app-api/.qoder/repowiki/zh/content/项目概述.md
T
yangy 36c6ca2766 新增功能
2026-05-27 18:07:55 +08:00

14 KiB
Raw Blame History

项目概述

**本文引用的文件** - [README.md](file://README.md) - [main.go](file://cmd/server/main.go) - [config.go](file://internal/config/config.go) - [router.go](file://internal/router/router.go) - [health.go](file://internal/handler/health.go) - [brand.go](file://internal/handler/brand.go) - [model.go](file://internal/handler/model.go) - [device.go](file://internal/handler/device.go) - [brand_repo.go](file://internal/repository/brand.go) - [response.go](file://internal/response/response.go) - [logger_mw.go](file://internal/middleware/logger.go) - [cors_mw.go](file://internal/middleware/cors.go) - [brand_model.go](file://internal/model/brand.go) - [model_model.go](file://internal/model/model.go) - [go.mod](file://go.mod)

目录

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

简介

本项目是一个基于 Gin 框架的 Go 语言 Web API 服务，专注于音频设备（耳机）数据管理。它采用清晰的分层架构，围绕“配置—路由—中间件—处理器—仓储—模型—响应”的结构组织代码，提供健康检查、品牌与型号查询、设备信息上报等能力，并通过统一响应体、日志与跨域中间件保证易用性与可观测性。

项目目标与定位：

  • 提供稳定、可扩展的音频设备数据 API 能力
  • 以 Gin 为核心，结合 MySQL、Redis、Meilisearch 等外部组件，满足查询、缓存与搜索需求
  • 通过统一响应体与中间件体系，降低接入成本，提升调试与运维效率

项目结构

项目采用按职责分层的目录组织方式，便于维护与扩展：

  • cmd/server：应用入口，负责初始化配置、数据库、搜索引擎与缓存客户端，构建路由引擎并启动 HTTP 服务器
  • internal/config：集中加载与校验运行时配置（环境、主机、端口、数据库、搜索引擎、Redis）
  • internal/router：路由注册与中间件装配，划分 /api/v1 与 /audio 两组路径空间
  • internal/handler：HTTP 处理器，承载业务逻辑，调用仓储与外部服务
  • internal/repository：数据访问层，封装 SQL 查询与结果映射
  • internal/model：领域模型定义，用于序列化与传输
  • internal/response：统一响应体封装，规范返回结构
  • internal/middleware：通用中间件（日志、CORS、请求 ID）
  • internal/search、internal/cache：对外部搜索与缓存服务的薄封装
  • pkg：可复用工具模块（如编码、日志）
  • sql：数据库初始化脚本
graph TB
subgraph "应用入口"
MAIN["cmd/server/main.go"]
end
subgraph "配置层"
CFG["internal/config/config.go"]
end
subgraph "路由与中间件"
RT["internal/router/router.go"]
MW_LOG["internal/middleware/logger.go"]
MW_CORS["internal/middleware/cors.go"]
end
subgraph "处理器"
H_HEALTH["internal/handler/health.go"]
H_BRAND["internal/handler/brand.go"]
H_MODEL["internal/handler/model.go"]
H_DEVICE["internal/handler/device.go"]
end
subgraph "仓储层"
REPO_BRAND["internal/repository/brand.go"]
end
subgraph "模型与响应"
M_BRAND["internal/model/brand.go"]
M_MODEL["internal/model/model.go"]
RESP["internal/response/response.go"]
end
subgraph "外部服务"
MYSQL["MySQL"]
REDIS["Redis"]
MEILI["Meilisearch"]
end
MAIN --> CFG
MAIN --> RT
RT --> MW_LOG
RT --> MW_CORS
RT --> H_HEALTH
RT --> H_BRAND
RT --> H_MODEL
RT --> H_DEVICE
H_BRAND --> REPO_BRAND
REPO_BRAND --> MYSQL
H_BRAND --> RESP
H_MODEL --> RESP
H_HEALTH --> RESP
H_DEVICE --> REDIS

图表来源

章节来源

核心组件

  • 配置加载与校验：集中读取环境变量，自动选择开发/生产数据库配置，校验搜索引擎与 Redis 配置的有效性
  • 路由与中间件：统一装配恢复、请求 ID、日志与跨域中间件；按 /api/v1 与 /audio 分组注册端点
  • 处理器层：品牌与型号查询处理器、健康检查处理器、设备信息上报处理器
  • 仓储层：SQL 查询封装，支持模糊匹配与排序
  • 统一响应体：标准化返回结构，简化前端对接
  • 外部集成：MySQL（持久化）、Redis（设备上报缓存/会话）、Meilisearch（可选搜索）

章节来源

架构总览

系统采用“入口初始化—配置—路由装配—处理器—仓储—外部服务”的线性控制流。入口负责加载配置、建立数据库与外部服务连接、构建 Gin 引擎并启动 HTTP 服务器；路由层装配中间件并注册各业务端点；处理器负责参数解析、调用仓储或外部服务、输出统一响应；仓储层封装 SQL 访问；响应体统一返回结构。

sequenceDiagram
participant Client as "客户端"
participant Main as "入口(main.go)"
participant Cfg as "配置(config.go)"
participant Router as "路由(router.go)"
participant Handler as "处理器(handler)"
participant Repo as "仓储(repository)"
participant DB as "MySQL"
Client->>Main : 启动进程
Main->>Cfg : 加载配置
Main->>Router : 构建引擎并注册路由
Client->>Router : 发起请求 /audio/getBrand
Router->>Handler : 调用处理器
Handler->>Repo : 执行查询
Repo->>DB : 执行 SQL
DB-->>Repo : 返回结果
Repo-->>Handler : 结果集
Handler-->>Client : 统一响应体

图表来源

详细组件分析

入口与生命周期管理

  • 初始化阶段：加载配置、设置 Gin 运行模式、初始化日志、建立数据库连接、配置搜索引擎与 Redis 客户端
  • 服务启动：创建 HTTP 服务器，设置超时参数，异步启动监听
  • 优雅关闭：捕获系统信号，执行超时上下文下的优雅停机
flowchart TD
Start(["进程启动"]) --> LoadCfg["加载配置"]
LoadCfg --> SetMode["设置 Gin 模式"]
SetMode --> InitLogger["初始化日志"]
InitLogger --> OpenDB["打开数据库连接"]
OpenDB --> InitSearch["初始化搜索引擎"]
InitSearch --> InitRedis["初始化 Redis"]
InitRedis --> BuildEngine["构建路由引擎"]
BuildEngine --> StartHTTP["启动 HTTP 服务"]
StartHTTP --> WaitSignal["等待系统信号"]
WaitSignal --> Graceful["优雅关闭"]
Graceful --> Stop(["进程结束"])

图表来源

章节来源

配置模块

  • 支持从环境变量读取运行环境、主机、端口、数据库、搜索引擎与 Redis 配置
  • 自动选择开发/生产数据库默认值，支持通过 DATABASE_* 环境变量覆盖
  • 对搜索引擎与 Redis 配置进行有效性校验

章节来源

路由与中间件

  • 中间件链：Recovery → RequestID → Logger → CORS
  • 路由分组：/api/v1（健康检查）、/audio（品牌/型号/设备相关接口）
  • 统一日志记录：记录状态码、方法、路径、延迟、客户端 IP、请求 ID 等

章节来源

品牌查询处理器

  • 功能：支持按品牌名称模糊查询，返回品牌列表；可选 Base64 编码响应
  • 流程：解析查询参数 → 调用仓储 → 错误处理 → 统一响应
sequenceDiagram
participant Client as "客户端"
participant Router as "路由"
participant Handler as "BrandHandler"
participant Repo as "BrandRepository"
participant DB as "MySQL"
Client->>Router : GET /audio/getBrand?brandName=...
Router->>Handler : 调用 GetBrand
Handler->>Repo : List(ctx, brandName)
Repo->>DB : 执行查询
DB-->>Repo : 结果集
Repo-->>Handler : 列表
Handler-->>Client : 统一响应体

图表来源

章节来源

型号查询处理器

  • 功能：支持按品牌与型号名称组合查询，返回型号列表；可选 Base64 编码响应
  • 流程：解析查询参数 → 调用仓储 → 错误处理 → 统一响应

章节来源

设备信息上报处理器

  • 功能：接收设备 MAC 地址、型号、版本与来源 IP，写入 Redis Hash 存储
  • 参数校验：必填字段校验，缺失时返回错误响应
  • 日志记录：记录远程 IP 与时间戳，便于审计与排障

章节来源

健康检查处理器

  • 功能：返回服务健康状态，统一响应体
  • 适用：容器编排与负载均衡探活

章节来源

统一响应体

  • 规范：包含 code、message、data 字段
  • 工具函数：OK、Fail、BadRequest、InternalError，便于在处理器中快速返回

章节来源

数据模型

  • 品牌模型：包含 id 与 name
  • 型号模型：包含品牌名、名称、形态、刚性、来源、EQ 键、创建时间等可空字段

章节来源

依赖分析

  • 技术栈概览：Go 1.24+、Gin、MySQL、Redis、Meilisearch、Zap
  • 模块依赖：入口依赖配置、数据库、缓存、路由与搜索模块；路由依赖处理器与中间件；处理器依赖仓储与响应体；仓储依赖数据库驱动；统一响应体被所有处理器使用
graph LR
MAIN["cmd/server/main.go"] --> CFG["internal/config/config.go"]
MAIN --> RT["internal/router/router.go"]
MAIN --> DB["internal/database/*"]
MAIN --> RC["internal/cache/*"]
MAIN --> SRCH["internal/search/*"]
RT --> H1["internal/handler/health.go"]
RT --> H2["internal/handler/brand.go"]
RT --> H3["internal/handler/model.go"]
RT --> H4["internal/handler/device.go"]
H2 --> REPO["internal/repository/brand.go"]
H3 --> RESP["internal/response/response.go"]
H4 --> REDIS["Redis"]
REPO --> MYSQL["MySQL"]

图表来源

章节来源

性能考虑

  • Gin 运行模式：生产环境启用 ReleaseMode，减少调试开销
  • 超时配置：HTTP 服务器设置读取、写入与空闲超时，避免资源占用
  • 日志级别：按状态码区分 Info/Warn/Error，避免高频错误日志影响性能
  • 查询优化：仓储层使用参数化查询与 LIKE 模糊匹配，建议在数据库侧为常用查询列建立索引
  • 缓存策略：设备上报使用 Redis Hash，建议结合过期策略与键空间清理

故障排查指南

  • 健康检查：通过 /api/v1/health 快速确认服务可用性
  • 日志定位：中间件记录请求详情与错误，结合请求 ID 快速定位问题
  • 数据库连接：入口日志会打印数据库连接信息，若连接失败需检查环境变量与网络连通性
  • Redis 写入：设备上报失败通常为 Redis HSet 异常，需检查 Redis 服务状态与键空间权限
  • 统一错误：处理器内部错误通过统一响应体返回，前端可根据 code/message 快速识别

章节来源

结论

本项目以 Gin 为核心，结合配置、路由、中间件、处理器、仓储与统一响应体的清晰分层，构建了面向音频设备数据管理的 API 服务。通过 MySQL、Redis、Meilisearch 的合理集成，满足查询、缓存与可扩展搜索的需求。项目结构清晰、易于扩展，适合初学者快速上手与资深开发者深度定制。

附录

  • 常见使用场景示例（基于现有端点）
    • 健康检查：GET /api/v1/health
    • 品牌列表：GET /audio/getBrand
    • 品牌模糊查询：GET /audio/getBrand?brandName=sony
    • 型号查询：GET /audio/getModel?brandName=sony&modelName=wh1000xm4
    • 设备信息上报：GET /audio/reportDevInfo?mac=XX:XX:XX:XX:XX:XX&model=WH-XXXX&ver=1.0

章节来源

Reference in New Issue View Git Blame Copy Permalink