backend/.qoder/repowiki/zh/content/API参考/系统API.md

系统API

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

目录

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

简介

本文件聚焦于系统相关的两个关键API：健康检查与系统配置获取。前者用于服务可用性监控，后者用于获取公开的全局配置项，帮助前端与运维侧快速了解站点状态与功能开关。文档将结合路由注册、处理器实现、模型与仓库层，给出端点定义、响应结构、调用流程与最佳实践，并说明Swagger文档的访问方式。

项目结构

系统API位于内部处理层（handler），通过路由注册挂载至Gin引擎；系统配置模型与仓库层负责持久化与查询；Swagger文档通过中间件暴露静态页面与健康检查端点。

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
• internal/handler/swagger.go
• internal/model/system_config.go
• internal/repository/system_config_repository.go

章节来源

• internal/handler/routes.go
• internal/handler/swagger.go
• internal/model/system_config.go
• internal/repository/system_config_repository.go

核心组件

• 健康检查端点
  • 路径：/health
  • 方法：GET
  • 作用：返回服务运行状态，便于Kubernetes、负载均衡器或监控系统进行存活探针与就绪探针
  • 响应：包含状态与消息字段的对象
• 系统配置端点
  • 路径：/api/v1/system/config
  • 方法：GET
  • 作用：返回公开的系统配置集合，供前端渲染站点标题、描述、注册开关、用户限制等
  • 当前实现：返回硬编码的公开配置；后续可替换为从数据库读取

章节来源

• internal/handler/swagger.go
• internal/handler/routes.go

架构总览

系统API的调用链路如下：客户端请求 -> Gin路由 -> 处理器函数 -> 仓库层（当前为内存返回，未来可改为数据库查询）-> 返回响应。

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
• internal/handler/routes.go

详细组件分析

健康检查端点 /health

• 注册位置：Swagger设置函数中注册了 /health 路由
• 处理逻辑：返回固定的成功状态与消息
• 响应结构：包含状态与消息字段的对象
• 用途：作为Kubernetes探针、负载均衡器健康检查、CI流水线可用性检测

flowchart TD
Start(["请求进入 /health"]) --> Check["调用 HealthCheck()"]
Check --> BuildResp["构建响应对象<br/>包含 status 与 message"]
BuildResp --> Return["返回 200 OK"]

图表来源

• internal/handler/swagger.go

章节来源

• internal/handler/swagger.go

系统配置端点 /api/v1/system/config

• 注册位置：v1路由组下的 /system/config
• 处理逻辑：当前实现返回硬编码的公开配置；注释提示后续应从数据库读取
• 响应结构：当前返回包含站点名称、描述、注册开关、每用户材质与档案上限等字段的对象
• 模型与仓库：
  • 模型定义了公开配置的结构（站点名称、描述、注册开关、维护模式、公告等）
  • 仓库提供了获取公开配置的方法（按 is_public 过滤）

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
• internal/model/system_config.go
• internal/repository/system_config_repository.go

章节来源

• internal/handler/routes.go
• internal/model/system_config.go
• internal/repository/system_config_repository.go

Swagger 文档访问

• 路由：/swagger/*any
• 作用：提供交互式API文档，便于开发者与测试人员查阅接口定义、参数与示例
• 项目说明：README中明确给出了Swagger文档地址与健康检查地址

章节来源

• internal/handler/swagger.go
• README.md

依赖分析

• 路由注册依赖：
  • Swagger设置函数负责注册 /health 与 /swagger/*any
  • v1路由组负责注册 /api/v1/system/config
• 处理器依赖：
  • GetSystemConfig 当前为内存返回；若改为数据库读取，则依赖仓库层的公开配置查询
• 模型与仓库：
  • SystemConfig 模型定义公开配置字段
  • 仓库层提供按 is_public 过滤的查询方法

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
• internal/handler/routes.go
• internal/repository/system_config_repository.go
• internal/model/system_config.go

章节来源

• internal/handler/swagger.go
• internal/handler/routes.go
• internal/repository/system_config_repository.go
• internal/model/system_config.go

性能考虑

• 健康检查：纯内存返回，延迟极低，适合高频探针
• 系统配置：
  • 当前为内存返回，避免数据库开销
  • 若切换为数据库查询，建议：
    • 对公开配置建立索引（如按 is_public 过滤）
    • 引入缓存层（如Redis）短期缓存公开配置，减少数据库压力
    • 控制响应大小，仅返回必要字段
• Swagger文档：静态文件托管，对性能影响可忽略

故障排查指南

• 健康检查失败
  • 检查服务进程是否正常运行
  • 确认 /health 路由已注册（Swagger设置函数）
  • 使用浏览器或curl访问 /health，观察返回状态与内容
• 系统配置端点异常
  • 当前实现为内存返回，若返回异常，检查处理器逻辑
  • 若切换为数据库查询，检查数据库连接、表是否存在、字段是否正确
• Swagger文档无法访问
  • 确认 /swagger/*any 路由已注册
  • 访问 /swagger/index.html 查看文档
  • 若文档为空，检查是否已生成Swagger文档

章节来源

• internal/handler/swagger.go
• internal/handler/routes.go
• README.md

结论

• /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
• internal/handler/routes.go
• README.md