Files

T

2026-05-27 18:07:55 +08:00

19 KiB

Raw Blame History

API 接口文档

**本文引用的文件** - [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)

简介

本文件为 Luxsin 应用 API 的完整接口文档，覆盖品牌管理、型号管理、设备上报与系统健康检查等接口。文档提供各接口的 HTTP 方法、URL 模式、请求参数、响应格式、错误处理、使用示例与最佳实践，并说明认证方式、速率限制策略、版本信息、客户端实现建议、调试与监控方法，以及向后兼容性与迁移注意事项。

项目结构

入口程序负责初始化配置、数据库、搜索引擎与缓存，构建路由并启动 HTTP 服务。
路由层按版本与业务域分组，注册各处理器。
处理器负责参数解析、调用仓储或搜索客户端、返回统一响应格式。
统一响应体封装了状态码、消息与数据字段，便于前端一致化处理。
中间件提供 CORS、日志与请求 ID 注入，便于跨域、可观测与追踪。
搜索与缓存分别对接 Meilisearch 与 Redis，支撑型号检索与设备上报数据存储。

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

图表来源

章节来源

核心组件

路由与中间件
- 路由在 /api/v1 下提供健康检查，在 /audio 下提供品牌、型号、型号检索与设备上报接口。
- 中间件链：恢复、请求 ID、日志、CORS。
统一响应
- 所有接口返回统一结构，包含 code、message、data 字段；错误时 code 为非零。
搜索与缓存
- 型号检索通过 Meilisearch 客户端完成；设备上报通过 Redis Hash 存储。
编码扩展
- 支持 base64Resp 参数，将响应体 JSON 再做自定义 Base64 编码传输，便于某些网络环境或协议需求。

章节来源

架构总览

以下序列图展示一次典型请求从接入到响应的全链路：

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)"

图表来源

详细接口说明

版本与基础信息

版本分组
- /api/v1：健康检查
- /audio：品牌、型号、型号检索、设备上报
认证方式
- 当前实现未内置鉴权逻辑，未发现显式的 Token/签名/密钥校验流程。
速率限制
- 当前实现未内置全局限流策略，如需请结合网关或中间件扩展。
基础响应结构
- 成功：code=0，message="ok"，data 为业务数据
- 失败：code 非 0，message 为错误描述
base64Resp
- 可选查询参数 base64Resp=true|1|空时，将响应体 JSON 再进行自定义 Base64 编码返回；默认开启。

章节来源

健康检查 /api/v1/health

方法与路径
- GET /api/v1/health
请求参数
- 无
响应
- data.status = "up"
错误处理
- 无内部错误路径，始终返回成功
使用场景
- 服务存活探测、负载均衡探活
示例
- curl: README.md:83-99

章节来源

品牌管理 /audio/getBrand

方法与路径
- GET /audio/getBrand
请求参数
- brandName: 可选，用于模糊过滤品牌名称
- base64Resp: 可选，是否对响应体进行二次 Base64 编码
响应数据
- 列表项包含品牌 id 与 name
错误处理
- 数据库查询异常：统一返回内部错误
- 编码异常：统一返回内部错误
使用场景
- 获取品牌列表，支持按名称模糊筛选
示例
- curl: README.md:101-109

章节来源

型号管理 /audio/getModel

方法与路径
- GET /audio/getModel
请求参数
- brandName: 可选，按品牌过滤
- modelName: 可选，按型号名称模糊过滤
- base64Resp: 可选，是否对响应体进行二次 Base64 编码
响应数据
- 列表项包含 id、brand_name、name、form、rig、source、eq_key、create_at；部分字段可能为空
错误处理
- 数据库查询异常：统一返回内部错误
- 编码异常：统一返回内部错误
使用场景
- 获取指定品牌或型号的详细列表
示例
- 无直接示例，但可通过组合 brandName 与 modelName 参数实现不同维度查询

章节来源

型号检索 /audio/modelList

方法与路径
- GET /audio/modelList
请求参数
- key: 必填，检索关键词
- count: 可选，最大返回条数，默认 100
- base64Resp: 可选，是否对响应体进行二次 Base64 编码
响应数据
- 列表项包含 rig、form、name、brand_name、source、eq_key 等字段
错误处理
- 搜索异常：统一返回内部错误
- 编码异常：统一返回内部错误
使用场景
- 基于关键词的型号检索，适用于推荐、搜索框等
示例
- 无直接示例，但可参考 Meilisearch 的检索行为

章节来源

设备上报 /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 写入失败：返回内部错误
使用场景
- 客户端上报设备活跃信息，便于后续统计与分析
示例
- 无直接示例，可参考响应结构与参数说明

章节来源

依赖关系分析

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

图表来源

性能与可用性

并发与超时
- 服务器设置读/写超时与空闲超时，避免慢请求占用资源。
日志与追踪
- 中间件记录状态码、方法、路径、延迟、IP、请求 ID，便于定位问题。
缓存与搜索
- 型号检索使用 Meilisearch，具备高性能全文检索能力；设备上报使用 Redis Hash，适合高并发写入。
响应体积控制
- base64Resp 可降低传输体积，但会增加 CPU 开销；建议在带宽受限或协议限制场景启用。
建议
- 对高频接口增加本地缓存（如品牌/型号列表）与 CDN 加速静态资源。
- 对设备上报接口增加幂等与去重策略，避免重复写入。

章节来源

故障排查指南

健康检查失败
- 检查 /api/v1/health 是否返回 status=up；若失败，查看服务日志与数据库连接状态。
品牌/型号接口异常
- 关注数据库连接与查询异常日志；确认 SQL 查询条件与参数传递正确。
型号检索失败
- 检查 Meilisearch 连接、索引配置与 API Key；确认关键词与返回字段。
设备上报失败
- 检查 Redis 连接与 HSET 写入；确认 mac 与 model 参数必填；关注 JSON 序列化错误。
统一错误响应
- 所有错误均通过统一响应体返回，code 非 0 表示失败，message 描述错误原因。

章节来源

结论

本项目采用清晰的分层架构与统一响应体设计，覆盖品牌、型号、检索与设备上报等核心业务场景。当前未内置鉴权与限流机制，建议在生产环境中补充安全与容量治理措施。通过中间件与日志体系，系统具备良好的可观测性，便于运维与排障。

附录

端到端调用流程（示例）

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"

图表来源

配置与部署要点

环境变量
- APP_ENV、APP_HOST、APP_PORT、GIN_MODE 等；数据库、Meilisearch、Redis 配置通过独立模块加载。
启动与运行
- 支持开发与生产模式；生产模式下 Gin 运行模式切换为 Release。
健康检查
- 提供 /api/v1/health 作为探活端点。

章节来源

19 KiB Raw Blame History Unescape Escape

API 接口文档

目录

简介

项目结构

核心组件

架构总览

详细接口说明

版本与基础信息

健康检查 /api/v1/health

品牌管理 /audio/getBrand

型号管理 /audio/getModel

型号检索 /audio/modelList

设备上报 /audio/reportDevInfo

依赖关系分析

性能与可用性

故障排查指南

结论

附录

端到端调用流程（示例）

配置与部署要点

19 KiB

Raw Blame History