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

27 KiB
Raw Permalink Blame History

核心模块

**本文引用的文件** - [cmd/server/main.go](file://cmd/server/main.go) - [internal/router/router.go](file://internal/router/router.go) - [internal/config/config.go](file://internal/config/config.go) - [internal/database/mysql.go](file://internal/database/mysql.go) - [internal/cache/redis.go](file://internal/cache/redis.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/handler/health.go](file://internal/handler/health.go) - [internal/repository/brand.go](file://internal/repository/brand.go) - [internal/repository/model.go](file://internal/repository/model.go) - [internal/model/brand.go](file://internal/model/brand.go) - [internal/model/model.go](file://internal/model/model.go) - [internal/response/response.go](file://internal/response/response.go) - [internal/search/meilisearch.go](file://internal/search/meilisearch.go) - [pkg/encode/base64.go](file://pkg/encode/base64.go) - [pkg/logger/logger.go](file://pkg/logger/logger.go)

目录

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

简介

本文件围绕 Luxsin 应用 API 的核心模块进行系统化文档化，重点覆盖以下方面：

  • 业务处理器（Handler）：负责接收请求、解析参数、调用仓库层、封装统一响应。
  • 数据访问层（Repository）：负责与数据库交互，执行查询与扫描逻辑。
  • 数据模型（Model）：定义持久化与对外传输的数据结构。
  • 统一响应（Response）：规范 HTTP 响应体格式，提供便捷的构造方法。
  • 依赖注入与启动流程：从配置加载到服务启动、中间件装配、路由注册与资源管理。
  • 错误处理与日志记录：在各层中的一致性错误处理与可观测性。
  • 扩展最佳实践：如何新增模块、如何复用编码器、如何接入缓存与搜索引擎。
  • 性能优化与并发安全：连接池、超时控制、上下文传播、Redis 并发安全。

项目结构

项目采用分层与按功能域组织的结构：

  • cmd/server：应用入口，负责配置加载、外部依赖初始化、HTTP 服务器启动与优雅关闭。
  • internal/config：集中式配置加载与校验。
  • internal/database：数据库连接与连接池配置。
  • internal/cache：Redis 客户端初始化。
  • internal/search：搜索引擎客户端封装。
  • internal/router：路由注册与中间件装配。
  • internal/handler：业务处理器，面向具体 API 路由。
  • internal/repository：数据访问层，封装 SQL 查询。
  • internal/model：领域模型与传输模型。
  • internal/response：统一响应体封装。
  • pkg/*：通用工具包（如编码器、日志）。
graph TB
subgraph "入口与配置"
MAIN["cmd/server/main.go<br/>应用入口"]
CFG["internal/config/config.go<br/>配置加载"]
end
subgraph "基础设施"
DB["internal/database/mysql.go<br/>MySQL 连接与池"]
RDS["internal/cache/redis.go<br/>Redis 客户端"]
SRCH["internal/search/meilisearch.go<br/>搜索引擎客户端"]
LOG["pkg/logger/logger.go<br/>日志"]
end
subgraph "服务编排"
RT["internal/router/router.go<br/>路由与中间件"]
end
subgraph "业务层"
H_BRAND["internal/handler/brand.go<br/>品牌处理器"]
H_MODEL["internal/handler/model.go<br/>型号处理器"]
H_MLIST["internal/handler/model_list.go<br/>型号搜索处理器"]
H_DEV["internal/handler/device.go<br/>设备上报处理器"]
H_HEALTH["internal/handler/health.go<br/>健康检查处理器"]
end
subgraph "数据访问与模型"
REPO_BRAND["internal/repository/brand.go<br/>品牌仓库"]
REPO_MODEL["internal/repository/model.go<br/>型号仓库"]
MODEL_BRAND["internal/model/brand.go<br/>品牌模型"]
MODEL_MODEL["internal/model/model.go<br/>型号模型"]
RESP["internal/response/response.go<br/>统一响应"]
ENC["pkg/encode/base64.go<br/>Base64 编码器"]
end
MAIN --> CFG
MAIN --> DB
MAIN --> RDS
MAIN --> SRCH
MAIN --> LOG
MAIN --> RT
RT --> H_HEALTH
RT --> H_BRAND
RT --> H_MODEL
RT --> H_MLIST
RT --> H_DEV
H_BRAND --> REPO_BRAND
H_MODEL --> REPO_MODEL
H_MLIST --> SRCH
H_DEV --> RDS
REPO_BRAND --> DB
REPO_MODEL --> DB
H_BRAND --> RESP
H_MODEL --> RESP
H_MLIST --> RESP
H_HEALTH --> RESP
H_BRAND --> ENC
H_MODEL --> ENC
H_MLIST --> ENC

图表来源

章节来源

核心组件

本节聚焦 Handler、Repository、Model、Response 四大核心模块的职责、协作方式与实现要点。

章节来源

架构总览

下图展示从请求进入至响应返回的关键路径，以及各层之间的依赖关系与调用方向。

sequenceDiagram
participant C as "客户端"
participant G as "Gin 路由<br/>internal/router/router.go"
participant H as "业务处理器<br/>internal/handler/*"
participant R as "仓库层<br/>internal/repository/*"
participant DB as "数据库<br/>internal/database/mysql.go"
participant S as "搜索引擎<br/>internal/search/meilisearch.go"
participant RC as "Redis<br/>internal/cache/redis.go"
participant RESP as "统一响应<br/>internal/response/response.go"
C->>G : "HTTP 请求"
G->>H : "匹配路由并调用处理器"
alt "品牌/型号列表"
H->>R : "调用仓库查询"
R->>DB : "执行 SQL 查询"
DB-->>R : "返回结果集"
R-->>H : "返回模型切片"
else "型号搜索"
H->>S : "调用搜索引擎"
S-->>H : "返回搜索结果"
else "设备上报"
H->>RC : "写入 Redis Hash"
RC-->>H : "返回写入结果"
end
H->>RESP : "构造统一响应"
RESP-->>C : "HTTP 响应"

图表来源

详细组件分析

Handler 层

  • 品牌处理器（BrandHandler）
    • 关键点：读取查询参数、调用仓库、错误日志与统一错误响应、可选 Base64 响应。
    • 参考路径：internal/handler/brand.go:26-49
  • 型号处理器（ModelHandler）
  • 型号搜索处理器（ModelListHandler）
  • 设备上报处理器（DeviceHandler）
  • 健康检查处理器（HealthHandler） 
classDiagram
class BrandHandler {
-repo : BrandRepository
-log : Logger
+GetBrand(c)
}
class ModelHandler {
-repo : ModelRepository
-log : Logger
+GetModel(c)
}
class ModelListHandler {
-search : SearchClient
-log : Logger
+ModelList(c)
}
class DeviceHandler {
-redis : RedisClient
-log : Logger
+ReportDevInfo(c)
}
class HealthHandler {
+Check(c)
}
BrandHandler --> BrandRepository : "依赖"
ModelHandler --> ModelRepository : "依赖"
ModelListHandler --> SearchClient : "依赖"
DeviceHandler --> RedisClient : "依赖"

图表来源

章节来源

Repository 层

classDiagram
class BrandRepository {
-db : sql.DB
+List(ctx, brandName) []Brand
}
class ModelRepository {
-db : sql.DB
+List(ctx, brandName, modelName) []Model
}
class Brand {
+id : int
+name : string
}
class Model {
+id : int
+brandName : string
+name : string
+form : *string
+rig : *string
+source : *string
+eqKey : *string
+createAt : time
}
BrandRepository --> Brand : "返回"
ModelRepository --> Model : "返回"

图表来源

章节来源

Model 层

章节来源

Response 层

flowchart TD
Start(["进入处理器"]) --> Build["构造响应体<br/>OK/Fail/BadRequest/InternalError"]
Build --> Send["通过 Gin 写入 HTTP 响应"]
Send --> End(["完成"])

图表来源

章节来源

编码与日志

章节来源

依赖分析

graph LR
MAIN["cmd/server/main.go"] --> CFG["internal/config/config.go"]
MAIN --> DB["internal/database/mysql.go"]
MAIN --> RDS["internal/cache/redis.go"]
MAIN --> RT["internal/router/router.go"]
RT --> H_BRAND["internal/handler/brand.go"]
RT --> H_MODEL["internal/handler/model.go"]
RT --> H_MLIST["internal/handler/model_list.go"]
RT --> H_DEV["internal/handler/device.go"]
H_BRAND --> REPO_BRAND["internal/repository/brand.go"]
H_MODEL --> REPO_MODEL["internal/repository/model.go"]
H_MLIST --> SRCH["internal/search/meilisearch.go"]
H_DEV --> RDS
REPO_BRAND --> DB
REPO_MODEL --> DB

图表来源

章节来源

性能考量

章节来源

故障排查指南

章节来源

结论

本项目通过清晰的分层与职责分离，实现了可维护、可扩展且具备良好性能特征的 API 服务：

  • Handler 专注于业务编排与响应封装；
  • Repository 将数据访问细节抽象化；
  • Model 明确数据契约；
  • Response 提供统一的对外接口；
  • 配合中间件、日志与统一错误处理，形成完整的可观测与可诊断体系；
  • 在数据库连接池、上下文超时、Redis 并发安全与可选 Base64 响应等方面体现了工程化细节。

附录

Reference in New Issue View Git Blame Copy Permalink