466 lines
19 KiB
Markdown
466 lines
19 KiB
Markdown
|
# 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)
|