261 lines
11 KiB
Markdown
261 lines
11 KiB
Markdown
# 系统API
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [internal/handler/swagger.go](file://internal/handler/swagger.go)
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go)
|
||
- [internal/model/system_config.go](file://internal/model/system_config.go)
|
||
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go)
|
||
- [README.md](file://README.md)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件聚焦于系统相关的两个关键API：健康检查与系统配置获取。前者用于服务可用性监控，后者用于获取公开的全局配置项，帮助前端与运维侧快速了解站点状态与功能开关。文档将结合路由注册、处理器实现、模型与仓库层，给出端点定义、响应结构、调用流程与最佳实践，并说明Swagger文档的访问方式。
|
||
|
||
## 项目结构
|
||
系统API位于内部处理层（handler），通过路由注册挂载至Gin引擎；系统配置模型与仓库层负责持久化与查询；Swagger文档通过中间件暴露静态页面与健康检查端点。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "路由与处理器"
|
||
Routes["routes.go<br/>注册 /api/v1/system/config"]
|
||
Swagger["swagger.go<br/>注册 /health 与 /swagger/*any"]
|
||
Health["HealthCheck()<br/>返回 {status,message}"]
|
||
SysCfg["GetSystemConfig()<br/>返回公开配置"]
|
||
end
|
||
subgraph "模型与仓库"
|
||
ModelSC["SystemConfig 模型<br/>公开字段: site_name, registration_enabled, ..."]
|
||
RepoSC["system_config_repository<br/>GetPublicSystemConfigs()"]
|
||
end
|
||
Routes --> SysCfg
|
||
Swagger --> Health
|
||
SysCfg --> RepoSC
|
||
RepoSC --> ModelSC
|
||
```
|
||
|
||
图表来源
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
|
||
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)
|
||
- [internal/model/system_config.go](file://internal/model/system_config.go#L17-L41)
|
||
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go#L25-L34)
|
||
|
||
章节来源
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
|
||
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)
|
||
- [internal/model/system_config.go](file://internal/model/system_config.go#L17-L41)
|
||
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go#L25-L34)
|
||
|
||
## 核心组件
|
||
- 健康检查端点
|
||
- 路径：/health
|
||
- 方法：GET
|
||
- 作用：返回服务运行状态，便于Kubernetes、负载均衡器或监控系统进行存活探针与就绪探针
|
||
- 响应：包含状态与消息字段的对象
|
||
- 系统配置端点
|
||
- 路径：/api/v1/system/config
|
||
- 方法：GET
|
||
- 作用：返回公开的系统配置集合，供前端渲染站点标题、描述、注册开关、用户限制等
|
||
- 当前实现：返回硬编码的公开配置；后续可替换为从数据库读取
|
||
|
||
章节来源
|
||
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
|
||
|
||
## 架构总览
|
||
系统API的调用链路如下：客户端请求 -> Gin路由 -> 处理器函数 -> 仓库层（当前为内存返回，未来可改为数据库查询）-> 返回响应。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant R as "Gin路由"
|
||
participant H as "处理器"
|
||
participant M as "模型/仓库(当前为内存)"
|
||
participant S as "Swagger/健康检查"
|
||
C->>R : GET /health
|
||
R->>S : HealthCheck()
|
||
S-->>C : {status,message}
|
||
C->>R : GET /api/v1/system/config
|
||
R->>H : GetSystemConfig()
|
||
H->>M : 当前返回硬编码公开配置
|
||
M-->>H : 公开配置对象
|
||
H-->>C : 成功响应
|
||
```
|
||
|
||
图表来源
|
||
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
|
||
|
||
## 详细组件分析
|
||
|
||
### 健康检查端点 /health
|
||
- 注册位置：Swagger设置函数中注册了 /health 路由
|
||
- 处理逻辑：返回固定的成功状态与消息
|
||
- 响应结构：包含状态与消息字段的对象
|
||
- 用途：作为Kubernetes探针、负载均衡器健康检查、CI流水线可用性检测
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["请求进入 /health"]) --> Check["调用 HealthCheck()"]
|
||
Check --> BuildResp["构建响应对象<br/>包含 status 与 message"]
|
||
BuildResp --> Return["返回 200 OK"]
|
||
```
|
||
|
||
图表来源
|
||
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)
|
||
|
||
章节来源
|
||
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)
|
||
|
||
### 系统配置端点 /api/v1/system/config
|
||
- 注册位置：v1路由组下的 /system/config
|
||
- 处理逻辑：当前实现返回硬编码的公开配置；注释提示后续应从数据库读取
|
||
- 响应结构：当前返回包含站点名称、描述、注册开关、每用户材质与档案上限等字段的对象
|
||
- 模型与仓库：
|
||
- 模型定义了公开配置的结构（站点名称、描述、注册开关、维护模式、公告等）
|
||
- 仓库提供了获取公开配置的方法（按 is_public 过滤）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant R as "Gin路由"
|
||
participant H as "GetSystemConfig()"
|
||
participant Repo as "GetPublicSystemConfigs()"
|
||
participant DB as "数据库"
|
||
C->>R : GET /api/v1/system/config
|
||
R->>H : 调用处理器
|
||
alt 当前实现为内存返回
|
||
H-->>C : 返回硬编码公开配置
|
||
else 后续实现为数据库读取
|
||
H->>Repo : 查询 is_public=true 的配置
|
||
Repo->>DB : 执行查询
|
||
DB-->>Repo : 返回配置列表
|
||
Repo-->>H : 配置对象
|
||
H-->>C : 返回公开配置
|
||
end
|
||
```
|
||
|
||
图表来源
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
|
||
- [internal/model/system_config.go](file://internal/model/system_config.go#L17-L41)
|
||
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go#L25-L34)
|
||
|
||
章节来源
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
|
||
- [internal/model/system_config.go](file://internal/model/system_config.go#L17-L41)
|
||
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go#L25-L34)
|
||
|
||
### Swagger 文档访问
|
||
- 路由：/swagger/*any
|
||
- 作用：提供交互式API文档，便于开发者与测试人员查阅接口定义、参数与示例
|
||
- 项目说明：README中明确给出了Swagger文档地址与健康检查地址
|
||
|
||
章节来源
|
||
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L44)
|
||
- [README.md](file://README.md#L149-L153)
|
||
|
||
## 依赖分析
|
||
- 路由注册依赖：
|
||
- Swagger设置函数负责注册 /health 与 /swagger/*any
|
||
- v1路由组负责注册 /api/v1/system/config
|
||
- 处理器依赖：
|
||
- GetSystemConfig 当前为内存返回；若改为数据库读取，则依赖仓库层的公开配置查询
|
||
- 模型与仓库：
|
||
- SystemConfig 模型定义公开配置字段
|
||
- 仓库层提供按 is_public 过滤的查询方法
|
||
|
||
```mermaid
|
||
graph LR
|
||
Swagger["swagger.go"] --> Routes["routes.go"]
|
||
Routes --> HandlerSys["GetSystemConfig()"]
|
||
HandlerSys --> Repo["system_config_repository.go"]
|
||
Repo --> Model["system_config.go"]
|
||
```
|
||
|
||
图表来源
|
||
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L44)
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
|
||
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go#L25-L34)
|
||
- [internal/model/system_config.go](file://internal/model/system_config.go#L17-L41)
|
||
|
||
章节来源
|
||
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L44)
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
|
||
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go#L25-L34)
|
||
- [internal/model/system_config.go](file://internal/model/system_config.go#L17-L41)
|
||
|
||
## 性能考虑
|
||
- 健康检查：纯内存返回，延迟极低，适合高频探针
|
||
- 系统配置：
|
||
- 当前为内存返回，避免数据库开销
|
||
- 若切换为数据库查询，建议：
|
||
- 对公开配置建立索引（如按 is_public 过滤）
|
||
- 引入缓存层（如Redis）短期缓存公开配置，减少数据库压力
|
||
- 控制响应大小，仅返回必要字段
|
||
- Swagger文档：静态文件托管，对性能影响可忽略
|
||
|
||
## 故障排查指南
|
||
- 健康检查失败
|
||
- 检查服务进程是否正常运行
|
||
- 确认 /health 路由已注册（Swagger设置函数）
|
||
- 使用浏览器或curl访问 /health，观察返回状态与内容
|
||
- 系统配置端点异常
|
||
- 当前实现为内存返回，若返回异常，检查处理器逻辑
|
||
- 若切换为数据库查询，检查数据库连接、表是否存在、字段是否正确
|
||
- Swagger文档无法访问
|
||
- 确认 /swagger/*any 路由已注册
|
||
- 访问 /swagger/index.html 查看文档
|
||
- 若文档为空，检查是否已生成Swagger文档
|
||
|
||
章节来源
|
||
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L44)
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
|
||
- [README.md](file://README.md#L149-L153)
|
||
|
||
## 结论
|
||
- /health 提供轻量级服务可用性检查，适合作为探针与监控指标
|
||
- /api/v1/system/config 当前返回硬编码公开配置，满足前端基础展示需求；后续可无缝替换为数据库读取，配合缓存与索引提升性能
|
||
- Swagger文档提供便捷的接口浏览与调试入口，有助于开发与运维协作
|
||
|
||
## 附录
|
||
|
||
### API定义与响应示例
|
||
|
||
- 健康检查
|
||
- 方法：GET
|
||
- 路径：/health
|
||
- 响应示例（结构示意）：
|
||
- status: 字符串，表示服务状态
|
||
- message: 字符串，简要描述
|
||
- 用途：存活/就绪探针、CI流水线可用性检测
|
||
|
||
- 系统配置
|
||
- 方法：GET
|
||
- 路径：/api/v1/system/config
|
||
- 响应示例（结构示意）：
|
||
- site_name: 字符串，站点名称
|
||
- site_description: 字符串，站点描述
|
||
- registration_enabled: 布尔值，是否允许注册
|
||
- max_textures_per_user: 整数，每用户最大材质数
|
||
- max_profiles_per_user: 整数，每用户最大档案数
|
||
- 用途：前端渲染站点标题、描述、注册开关、用户限制等
|
||
|
||
- Swagger文档
|
||
- 访问路径：/swagger/index.html
|
||
- 用途：查看与调试所有API接口
|
||
|
||
章节来源
|
||
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
|
||
- [README.md](file://README.md#L149-L153) |