audio/app-api
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8c22be4e0af8088d6b9a753e02ce59fa8afafb0c
app-api/.qoder/repowiki/zh/content/API 接口文档/API 接口文档.md
T
yangy 36c6ca2766 新增功能
2026-05-27 18:07:55 +08:00

466 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API 接口文档
<cite>
**本文引用的文件**
- [cmd/server/main.go](file://cmd/server/main.go)
- [internal/router/router.go](file://internal/router/router.go)
- [internal/handler/health.go](file://internal/handler/health.go)
- [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/response/response.go](file://internal/response/response.go)
- [internal/middleware/cors.go](file://internal/middleware/cors.go)
- [internal/middleware/logger.go](file://internal/middleware/logger.go)
- [internal/middleware/request_id.go](file://internal/middleware/request_id.go)
- [internal/search/meilisearch.go](file://internal/search/meilisearch.go)
- [internal/repository/brand.go](file://internal/repository/brand.go)
- [internal/repository/model.go](file://internal/repository/model.go)
- [pkg/encode/base64.go](file://pkg/encode/base64.go)
- [internal/config/config.go](file://internal/config/config.go)
- [README.md](file://README.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细接口说明](#详细接口说明)
6. [依赖关系分析](#依赖关系分析)
7. [性能与可用性](#性能与可用性)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件为 Luxsin 应用 API 的完整接口文档，覆盖品牌管理、型号管理、设备上报与系统健康检查等接口。文档提供各接口的 HTTP 方法、URL 模式、请求参数、响应格式、错误处理、使用示例与最佳实践，并说明认证方式、速率限制策略、版本信息、客户端实现建议、调试与监控方法，以及向后兼容性与迁移注意事项。
## 项目结构
- 入口程序负责初始化配置、数据库、搜索引擎与缓存，构建路由并启动 HTTP 服务。
- 路由层按版本与业务域分组，注册各处理器。
- 处理器负责参数解析、调用仓储或搜索客户端、返回统一响应格式。
- 统一响应体封装了状态码、消息与数据字段，便于前端一致化处理。
- 中间件提供 CORS、日志与请求 ID 注入，便于跨域、可观测与追踪。
- 搜索与缓存分别对接 Meilisearch 与 Redis，支撑型号检索与设备上报数据存储。
```mermaid
graph TB
subgraph "服务进程"
MAIN["cmd/server/main.go<br/>启动与生命周期"]
ROUTER["internal/router/router.go<br/>路由注册"]
end
subgraph "HTTP 层"
CORS["internal/middleware/cors.go<br/>CORS"]
LOGMW["internal/middleware/logger.go<br/>访问日志"]
RID["internal/middleware/request_id.go<br/>请求ID注入"]
end
subgraph "业务层"
HEALTH["internal/handler/health.go<br/>健康检查"]
BRAND["internal/handler/brand.go<br/>品牌列表"]
MODEL["internal/handler/model.go<br/>型号详情"]
MODELLIST["internal/handler/model_list.go<br/>型号检索"]
DEVICE["internal/handler/device.go<br/>设备上报"]
end
subgraph "数据与外部服务"
RESP["internal/response/response.go<br/>统一响应"]
DB["MySQL(由配置驱动)"]
MS["Meilisearch(由配置驱动)"]
REDIS["Redis(由配置驱动)"]
end
MAIN --> ROUTER
ROUTER --> CORS --> LOGMW --> RID
ROUTER --> HEALTH
ROUTER --> BRAND
ROUTER --> MODEL
ROUTER --> MODELLIST
ROUTER --> DEVICE
BRAND --> DB
MODEL --> DB
MODELLIST --> MS
DEVICE --> REDIS
HEALTH --> RESP
BRAND --> RESP
MODEL --> RESP
MODELLIST --> RESP
DEVICE --> RESP
```
图表来源
- [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/middleware/cors.go:7-21](file://internal/middleware/cors.go#L7-L21)
- [internal/middleware/logger.go:10-46](file://internal/middleware/logger.go#L10-L46)
- [internal/middleware/request_id.go:20-31](file://internal/middleware/request_id.go#L20-L31)
- [internal/handler/health.go:14-19](file://internal/handler/health.go#L14-L19)
- [internal/handler/brand.go:26-50](file://internal/handler/brand.go#L26-L50)
- [internal/handler/model.go:26-51](file://internal/handler/model.go#L26-L51)
- [internal/handler/model_list.go:26-57](file://internal/handler/model_list.go#L26-L57)
- [internal/handler/device.go:26-85](file://internal/handler/device.go#L26-L85)
- [internal/response/response.go:9-37](file://internal/response/response.go#L9-L37)
章节来源
- [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)
- [README.md:1-123](file://README.md#L1-L123)
## 核心组件
- 路由与中间件
- 路由在 /api/v1 下提供健康检查，在 /audio 下提供品牌、型号、型号检索与设备上报接口。
- 中间件链：恢复、请求 ID、日志、CORS。
- 统一响应
- 所有接口返回统一结构，包含 code、message、data 字段；错误时 code 为非零。
- 搜索与缓存
- 型号检索通过 Meilisearch 客户端完成；设备上报通过 Redis Hash 存储。
- 编码扩展
- 支持 base64Resp 参数，将响应体 JSON 再做自定义 Base64 编码传输，便于某些网络环境或协议需求。
章节来源
- [internal/router/router.go:14-42](file://internal/router/router.go#L14-L42)
- [internal/middleware/cors.go:7-21](file://internal/middleware/cors.go#L7-L21)
- [internal/middleware/logger.go:10-46](file://internal/middleware/logger.go#L10-L46)
- [internal/middleware/request_id.go:20-31](file://internal/middleware/request_id.go#L20-L31)
- [internal/response/response.go:9-37](file://internal/response/response.go#L9-L37)
- [internal/search/meilisearch.go:17-46](file://internal/search/meilisearch.go#L17-L46)
- [pkg/encode/base64.go:44-52](file://pkg/encode/base64.go#L44-L52)
## 架构总览
以下序列图展示一次典型请求从接入到响应的全链路：
```mermaid
sequenceDiagram
participant C as "客户端"
participant G as "Gin 路由"
participant MW as "中间件(CORS/日志/请求ID)"
participant H as "处理器"
participant S as "搜索/缓存/数据库"
C->>G : "HTTP 请求"
G->>MW : "中间件链"
MW-->>G : "注入请求ID/日志/CORS"
G->>H : "匹配路由并调用处理器"
H->>S : "读取/写入(数据库/搜索/缓存)"
S-->>H : "结果/错误"
H-->>G : "统一响应体"
G-->>C : "HTTP 响应(JSON/可选base64)"
```
图表来源
- [internal/router/router.go:27-38](file://internal/router/router.go#L27-L38)
- [internal/middleware/cors.go:7-21](file://internal/middleware/cors.go#L7-L21)
- [internal/middleware/logger.go:10-46](file://internal/middleware/logger.go#L10-L46)
- [internal/middleware/request_id.go:20-31](file://internal/middleware/request_id.go#L20-L31)
- [internal/handler/brand.go:26-50](file://internal/handler/brand.go#L26-L50)
- [internal/handler/model.go:26-51](file://internal/handler/model.go#L26-L51)
- [internal/handler/model_list.go:26-57](file://internal/handler/model_list.go#L26-L57)
- [internal/handler/device.go:26-85](file://internal/handler/device.go#L26-L85)
- [internal/response/response.go:15-37](file://internal/response/response.go#L15-L37)
## 详细接口说明
### 版本与基础信息
- 版本分组
- /api/v1：健康检查
- /audio：品牌、型号、型号检索、设备上报
- 认证方式
- 当前实现未内置鉴权逻辑，未发现显式的 Token/签名/密钥校验流程。
- 速率限制
- 当前实现未内置全局限流策略，如需请结合网关或中间件扩展。
- 基础响应结构
- 成功：code=0，message="ok"，data 为业务数据
- 失败：code 非 0，message 为错误描述
- base64Resp
- 可选查询参数 base64Resp=true|1|空 时，将响应体 JSON 再进行自定义 Base64 编码返回；默认开启。
章节来源
- [internal/router/router.go:27-38](file://internal/router/router.go#L27-L38)
- [internal/response/response.go:9-37](file://internal/response/response.go#L9-L37)
- [pkg/encode/base64.go:44-52](file://pkg/encode/base64.go#L44-L52)
### 健康检查 /api/v1/health
- 方法与路径
- GET /api/v1/health
- 请求参数
- 无
- 响应
- data.status = "up"
- 错误处理
- 无内部错误路径，始终返回成功
- 使用场景
- 服务存活探测、负载均衡探活
- 示例
- curl: [README.md:83-99](file://README.md#L83-L99)
章节来源
- [internal/router/router.go:29](file://internal/router/router.go#L29)
- [internal/handler/health.go:14-19](file://internal/handler/health.go#L14-L19)
- [README.md:83-99](file://README.md#L83-L99)
### 品牌管理 /audio/getBrand
- 方法与路径
- GET /audio/getBrand
- 请求参数
- brandName: 可选，用于模糊过滤品牌名称
- base64Resp: 可选，是否对响应体进行二次 Base64 编码
- 响应数据
- 列表项包含品牌 id 与 name
- 错误处理
- 数据库查询异常：统一返回内部错误
- 编码异常：统一返回内部错误
- 使用场景
- 获取品牌列表，支持按名称模糊筛选
- 示例
- curl: [README.md:101-109](file://README.md#L101-L109)
章节来源
- [internal/router/router.go:34](file://internal/router/router.go#L34)
- [internal/handler/brand.go:26-50](file://internal/handler/brand.go#L26-L50)
- [internal/repository/brand.go:20-51](file://internal/repository/brand.go#L20-L51)
- [internal/response/response.go:15-37](file://internal/response/response.go#L15-L37)
- [pkg/encode/base64.go:44-52](file://pkg/encode/base64.go#L44-L52)
- [README.md:101-109](file://README.md#L101-L109)
### 型号管理 /audio/getModel
- 方法与路径
- GET /audio/getModel
- 请求参数
- brandName: 可选，按品牌过滤
- modelName: 可选，按型号名称模糊过滤
- base64Resp: 可选，是否对响应体进行二次 Base64 编码
- 响应数据
- 列表项包含 id、brand_name、name、form、rig、source、eq_key、create_at；部分字段可能为空
- 错误处理
- 数据库查询异常：统一返回内部错误
- 编码异常：统一返回内部错误
- 使用场景
- 获取指定品牌或型号的详细列表
- 示例
- 无直接示例，但可通过组合 brandName 与 modelName 参数实现不同维度查询
章节来源
- [internal/router/router.go:35](file://internal/router/router.go#L35)
- [internal/handler/model.go:26-51](file://internal/handler/model.go#L26-L51)
- [internal/repository/model.go:20-95](file://internal/repository/model.go#L20-L95)
- [internal/response/response.go:15-37](file://internal/response/response.go#L15-L37)
- [pkg/encode/base64.go:44-52](file://pkg/encode/base64.go#L44-L52)
### 型号检索 /audio/modelList
- 方法与路径
- GET /audio/modelList
- 请求参数
- key: 必填，检索关键词
- count: 可选，最大返回条数，默认 100
- base64Resp: 可选，是否对响应体进行二次 Base64 编码
- 响应数据
- 列表项包含 rig、form、name、brand_name、source、eq_key 等字段
- 错误处理
- 搜索异常：统一返回内部错误
- 编码异常：统一返回内部错误
- 使用场景
- 基于关键词的型号检索，适用于推荐、搜索框等
- 示例
- 无直接示例，但可参考 Meilisearch 的检索行为
章节来源
- [internal/router/router.go:36](file://internal/router/router.go#L36)
- [internal/handler/model_list.go:26-57](file://internal/handler/model_list.go#L26-L57)
- [internal/search/meilisearch.go:22-46](file://internal/search/meilisearch.go#L22-L46)
- [internal/response/response.go:15-37](file://internal/response/response.go#L15-L37)
- [pkg/encode/base64.go:44-52](file://pkg/encode/base64.go#L44-L52)
### 设备上报 /audio/reportDevInfo
- 方法与路径
- GET /audio/reportDevInfo
- 请求参数
- mac: 必填，设备 MAC 地址
- model: 必填，设备型号
- ver: 可选，版本号
- X-Forwarded-For: 可选，客户端 IP（由代理注入）
- 响应
- 成功：code=200，msg="操作成功"
- 参数缺失：code=400，msg="参数校验失败"
- 系统错误：code=500，msg="系统错误"
- 存储行为
- 将设备信息以 JSON 形式写入 Redis Hash，键为 devices，field 为 mac
- 错误处理
- 参数校验失败：返回业务错误
- JSON 序列化失败：返回内部错误
- Redis 写入失败：返回内部错误
- 使用场景
- 客户端上报设备活跃信息，便于后续统计与分析
- 示例
- 无直接示例，可参考响应结构与参数说明
章节来源
- [internal/router/router.go:37](file://internal/router/router.go#L37)
- [internal/handler/device.go:26-85](file://internal/handler/device.go#L26-L85)
- [internal/response/response.go:15-37](file://internal/response/response.go#L15-L37)
## 依赖关系分析
```mermaid
classDiagram
class Router {
+New(log, db, search, redis) Engine
}
class HealthHandler
class BrandHandler {
-repo BrandRepository
+GetBrand(c)
}
class ModelHandler {
-repo ModelRepository
+GetModel(c)
}
class ModelListHandler {
-search SearchClient
+ModelList(c)
}
class DeviceHandler {
-redis RedisClient
+ReportDevInfo(c)
}
class BrandRepository {
+List(ctx, brandName) []Brand
}
class ModelRepository {
+List(ctx, brandName, modelName) []Model
}
class SearchClient {
+ModelList(ctx, key, count) []map
}
class Response {
+OK(c, data)
+Fail(c, httpStatus, code, msg)
+BadRequest(c, msg)
+InternalError(c, msg)
}
class Middleware_CORS
class Middleware_Logger
class Middleware_RequestID
Router --> HealthHandler
Router --> BrandHandler
Router --> ModelHandler
Router --> ModelListHandler
Router --> DeviceHandler
BrandHandler --> BrandRepository
ModelHandler --> ModelRepository
ModelListHandler --> SearchClient
DeviceHandler --> Response
BrandHandler --> Response
ModelHandler --> Response
ModelListHandler --> Response
HealthHandler --> Response
Router --> Middleware_CORS
Router --> Middleware_Logger
Router --> Middleware_RequestID
```
图表来源
- [internal/router/router.go:14-42](file://internal/router/router.go#L14-L42)
- [internal/handler/health.go:8-18](file://internal/handler/health.go#L8-L18)
- [internal/handler/brand.go:14-24](file://internal/handler/brand.go#L14-L24)
- [internal/handler/model.go:14-24](file://internal/handler/model.go#L14-L24)
- [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)
- [internal/repository/brand.go:12-18](file://internal/repository/brand.go#L12-L18)
- [internal/repository/model.go:12-18](file://internal/repository/model.go#L12-L18)
- [internal/search/meilisearch.go:13-20](file://internal/search/meilisearch.go#L13-L20)
- [internal/response/response.go:9-37](file://internal/response/response.go#L9-L37)
- [internal/middleware/cors.go:7-21](file://internal/middleware/cors.go#L7-L21)
- [internal/middleware/logger.go:10-46](file://internal/middleware/logger.go#L10-L46)
- [internal/middleware/request_id.go:20-31](file://internal/middleware/request_id.go#L20-L31)
## 性能与可用性
- 并发与超时
- 服务器设置读/写超时与空闲超时，避免慢请求占用资源。
- 日志与追踪
- 中间件记录状态码、方法、路径、延迟、IP、请求 ID，便于定位问题。
- 缓存与搜索
- 型号检索使用 Meilisearch，具备高性能全文检索能力；设备上报使用 Redis Hash，适合高并发写入。
- 响应体积控制
- base64Resp 可降低传输体积，但会增加 CPU 开销；建议在带宽受限或协议限制场景启用。
- 建议
- 对高频接口增加本地缓存（如品牌/型号列表）与 CDN 加速静态资源。
- 对设备上报接口增加幂等与去重策略，避免重复写入。
章节来源
- [cmd/server/main.go:66-72](file://cmd/server/main.go#L66-L72)
- [internal/middleware/logger.go:10-46](file://internal/middleware/logger.go#L10-L46)
- [internal/search/meilisearch.go:22-46](file://internal/search/meilisearch.go#L22-L46)
- [pkg/encode/base64.go:44-52](file://pkg/encode/base64.go#L44-L52)
## 故障排查指南
- 健康检查失败
- 检查 /api/v1/health 是否返回 status=up；若失败，查看服务日志与数据库连接状态。
- 品牌/型号接口异常
- 关注数据库连接与查询异常日志；确认 SQL 查询条件与参数传递正确。
- 型号检索失败
- 检查 Meilisearch 连接、索引配置与 API Key；确认关键词与返回字段。
- 设备上报失败
- 检查 Redis 连接与 HSET 写入；确认 mac 与 model 参数必填；关注 JSON 序列化错误。
- 统一错误响应
- 所有错误均通过统一响应体返回，code 非 0 表示失败，message 描述错误原因。
章节来源
- [internal/handler/health.go:14-19](file://internal/handler/health.go#L14-L19)
- [internal/handler/brand.go:30-35](file://internal/handler/brand.go#L30-L35)
- [internal/handler/model.go:31-36](file://internal/handler/model.go#L31-L36)
- [internal/handler/model_list.go:37-42](file://internal/handler/model_list.go#L37-L42)
- [internal/handler/device.go:61-78](file://internal/handler/device.go#L61-L78)
- [internal/response/response.go:23-37](file://internal/response/response.go#L23-L37)
## 结论
本项目采用清晰的分层架构与统一响应体设计，覆盖品牌、型号、检索与设备上报等核心业务场景。当前未内置鉴权与限流机制，建议在生产环境中补充安全与容量治理措施。通过中间件与日志体系，系统具备良好的可观测性，便于运维与排障。
## 附录
### 端到端调用流程（示例）
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Router as "路由"
participant Handler as "处理器"
participant DBMS as "数据库"
participant Search as "Meilisearch"
participant Cache as "Redis"
Client->>Router : "GET /audio/getBrand?brandName=sony"
Router->>Handler : "GetBrand"
Handler->>DBMS : "查询品牌列表"
DBMS-->>Handler : "品牌列表"
Handler-->>Router : "统一响应"
Router-->>Client : "JSON/可选base64"
Client->>Router : "GET /audio/modelList?key=wha&count=50"
Router->>Handler : "ModelList"
Handler->>Search : "关键词检索"
Search-->>Handler : "检索结果"
Handler-->>Router : "统一响应"
Router-->>Client : "JSON/可选base64"
Client->>Router : "GET /audio/reportDevInfo?mac=xx&model=yy&ver=v1"
Router->>Handler : "ReportDevInfo"
Handler->>Cache : "HSET devices : mac -> JSON"
Cache-->>Handler : "写入成功"
Handler-->>Router : "统一响应"
Router-->>Client : "JSON"
```
图表来源
- [internal/router/router.go:34-37](file://internal/router/router.go#L34-L37)
- [internal/handler/brand.go:26-50](file://internal/handler/brand.go#L26-L50)
- [internal/handler/model_list.go:26-57](file://internal/handler/model_list.go#L26-L57)
- [internal/handler/device.go:26-85](file://internal/handler/device.go#L26-L85)
- [internal/repository/brand.go:20-51](file://internal/repository/brand.go#L20-L51)
- [internal/search/meilisearch.go:22-46](file://internal/search/meilisearch.go#L22-L46)
### 配置与部署要点
- 环境变量
- APP_ENV、APP_HOST、APP_PORT、GIN_MODE 等；数据库、Meilisearch、Redis 配置通过独立模块加载。
- 启动与运行
- 支持开发与生产模式；生产模式下 Gin 运行模式切换为 Release。
- 健康检查
- 提供 /api/v1/health 作为探活端点。
章节来源
- [internal/config/config.go:18-64](file://internal/config/config.go#L18-L64)
- [cmd/server/main.go:28-30](file://cmd/server/main.go#L28-L30)
- [README.md:83-99](file://README.md#L83-L99)
Reference in New Issue View Git Blame Copy Permalink