跳到主要内容

基础设施API

引用文件

本文引用的文件

目录​

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

简介​

本文件面向基础设施服务的API使用者与运维人员，系统性梳理配置管理、文件管理、日志管理与WebSocket推送四大核心能力的接口规范与实现要点。文档覆盖：

  • 配置项查询接口：通过统一RPC服务查询配置值
  • 文件上传/下载/删除接口：统一文件存储与访问路径管理
  • API访问日志与错误日志：日志采集、分页查询、清理策略与处理流程
  • WebSocket推送接口：基于会话/用户/用户类型定向推送消息
  • 监控与运维：Redis、MySQL、中间件等监控入口与最佳实践

项目结构​

基础设施模块采用“API接口 + 业务实现”的分层组织方式，配合统一的RPC常量与配置，确保跨模块调用的一致性与可维护性。

Mermaid Diagram Code:

graph TB
subgraph "基础设施API层"
CFG["ConfigApi 接口"]
FAPI["FileApi 接口"]
WSAPI["WebSocketSenderApi 接口"]
end
subgraph "基础设施业务层"
CFGIMPL["ConfigApiImpl 实现"]
FILEIMPL["FileApiImpl 实现"]
WSSIMPL["WebSocketSenderApiImpl 实现"]
end
subgraph "日志服务层"
ACCESSLOG["ApiAccessLogService 接口"]
ERRORLOG["ApiErrorLogService 接口"]
ERRORLOGIMPL["ApiErrorLogServiceImpl 实现"]
end
CFG --> CFGIMPL
FAPI --> FILEIMPL
WSAPI --> WSSIMPL
ERRORLOG --> ERRORLOGIMPL

图表来源

章节来源

核心组件​

  • 配置管理接口：提供按键查询配置值的RPC接口，便于各模块动态获取配置
  • 文件管理接口：提供文件创建、按ID/URL查询与删除能力，统一返回可访问路径
  • 日志管理接口：提供访问日志与错误日志的创建、分页查询、清理与处理更新
  • WebSocket推送接口：提供消息发送器封装，支持按会话、用户或用户类型定向推送

章节来源

架构总览​

基础设施服务通过统一RPC前缀暴露REST风格的Feign接口，业务模块通过依赖注入调用；日志服务负责采集与持久化访问/错误日志；WebSocket消息发送器支持多通道推送。

Mermaid Diagram Code:

sequenceDiagram
participant Caller as "调用方模块"
participant InfraAPI as "基础设施API"
participant Impl as "基础设施实现"
participant LogSvc as "日志服务"
participant WS as "WebSocket发送器"
Caller->>InfraAPI : 调用配置/文件/日志/推送接口
InfraAPI->>Impl : Feign转发到具体实现
Impl->>LogSvc : 记录访问/错误日志
Impl->>WS : 发送WebSocket消息
Impl-->>InfraAPI : 返回通用结果
InfraAPI-->>Caller : 统一响应

图表来源

详细组件分析​

配置管理接口​

  • 服务名与前缀：通过统一枚举定义服务名与RPC前缀，确保跨模块一致性
  • 查询接口：按配置键查询配置值，返回字符串类型
  • 使用场景：动态配置下发、灰度开关、功能开关等

Mermaid Diagram Code:

sequenceDiagram
participant Client as "调用方"
participant ConfigAPI as "ConfigApi"
participant ConfigImpl as "ConfigApiImpl"
participant Store as "配置存储"
Client->>ConfigAPI : GET /infra/config/get-value-by-key?key=...
ConfigAPI->>ConfigImpl : Feign转发
ConfigImpl->>Store : 查询配置值
Store-->>ConfigImpl : 返回配置值
ConfigImpl-->>ConfigAPI : 包装为通用结果
ConfigAPI-->>Client : 返回字符串值

图表来源

章节来源

文件管理接口​

  • 创建文件：支持默认重载与多种入参形式，最终统一为创建请求DTO
  • 查询文件：按ID或URL查询文件元数据
  • 删除文件：按ID或URL删除文件
  • 返回约定：创建接口返回可访问路径，便于前端直接使用

Mermaid Diagram Code:

sequenceDiagram
participant Client as "调用方"
participant FileAPI as "FileApi"
participant FileImpl as "FileApiImpl"
participant Storage as "文件存储"
Client->>FileAPI : POST /infra/file/create (二进制内容)
FileAPI->>FileImpl : Feign转发
FileImpl->>Storage : 写入文件并生成访问路径
Storage-->>FileImpl : 返回文件元数据
FileImpl-->>FileAPI : 包装为通用结果
FileAPI-->>Client : 返回访问路径
Client->>FileAPI : GET /infra/file/get?id=...
Client->>FileAPI : GET /infra/file/getFileByUrl?url=...
Client->>FileAPI : DELETE /infra/file/delete/by/id?id=...
Client->>FileAPI : DELETE /infra/file/delete/by/url?url=...

图表来源

章节来源

日志管理接口​

  • 访问日志：记录接口调用详情、耗时、结果码等，支持分页查询与定时清理
  • 错误日志：记录异常堆栈、处理状态、处理人与时间，支持分页查询与处理更新
  • 控制台入口：提供访问日志与错误日志的管理界面入口

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> CreateAccess["创建访问日志"]
CreateAccess --> CreateError["创建错误日志"]
CreateError --> QueryAccess["分页查询访问日志"]
CreateError --> QueryError["分页查询错误日志"]
QueryAccess --> CleanAccess["清理超过阈值的访问日志"]
QueryError --> CleanError["清理超过阈值的错误日志"]
CleanAccess --> End(["结束"])
CleanError --> End

图表来源

章节来源

WebSocket推送接口​

  • 接口封装：对底层消息发送器进行RPC封装，支持按会话、用户或用户类型推送
  • 请求体：包含消息类型与消息内容（JSON格式），支持空会话ID的广播场景
  • 配置项：启用开关、路径、消息发送类型与多通道Topic/Exchange/Queue配置

Mermaid Diagram Code:

sequenceDiagram
participant Sender as "调用方"
participant WSAPI as "WebSocketSenderApi"
participant WSImpl as "WebSocketSenderApiImpl"
participant WSSender as "WebSocketMessageSender"
Sender->>WSAPI : POST /infra/websocket/send
WSAPI->>WSImpl : Feign转发
WSImpl->>WSSender : send(sessionId/userType+userId/messageType/content)
WSSender-->>WSImpl : 发送完成
WSImpl-->>WSAPI : 返回成功
WSAPI-->>Sender : 通用结果

图表来源

章节来源

依赖关系分析​

  • 统一RPC常量：ApiConstants集中定义服务名与前缀，避免硬编码
  • Feign接口：各模块通过FeignClient声明式调用基础设施服务
  • 业务实现：各API接口对应实现类，负责具体逻辑与外部存储交互
  • 日志服务：访问/错误日志分别由独立Service接口与实现类承载
  • WebSocket：发送器封装在API层，业务侧仅需关注消息内容与目标

Mermaid Diagram Code:

classDiagram
class ApiConstants {
+NAME
+PREFIX
+VERSION
}
class ConfigApi {
+getConfigValueByKey(key)
}
class ConfigApiImpl
class FileApi {
+createFile(...)
+getFile(id)
+getFileByUrl(url)
+deleteFileByUrl(url)
+deleteFileById(id)
}
class FileApiImpl
class WebSocketSenderApi {
+send(message)
}
class WebSocketSenderApiImpl
class WebSocketSendReqDTO
class ApiAccessLogService
class ApiErrorLogService
class ApiErrorLogServiceImpl
ConfigApi --> ApiConstants
FileApi --> ApiConstants
WebSocketSenderApi --> ApiConstants
ConfigApiImpl --> ConfigApi
FileApiImpl --> FileApi
WebSocketSenderApiImpl --> WebSocketSenderApi
WebSocketSenderApiImpl --> WebSocketSendReqDTO
ApiErrorLogServiceImpl --> ApiErrorLogService

图表来源

章节来源

性能考量​

  • 日志清理策略：访问/错误日志均提供按天清理与批量删除限制，建议结合数据量与存储成本制定清理周期
  • 文件存储：建议对大文件采用分块上传与CDN加速，减少单次传输压力
  • WebSocket：根据消息发送类型选择本地或消息队列（RocketMQ/Kafka/RabbitMQ）以提升扩展性与可靠性
  • 监控集成：通过Redis与MySQL监控面板及时发现资源瓶颈，必要时引入Grafana等可视化平台

故障排查指南​

  • 访问日志与错误日志
    • 通过管理界面定位问题接口，核对请求参数、响应结果与时长
    • 错误日志支持按用户、应用、异常时间与处理状态筛选，及时处理未处理异常
  • WebSocket推送
    • 确认消息类型与内容非空，检查目标会话或用户是否存在
    • 若使用消息队列，确认Topic/Exchange/Queue配置正确且消费者组可用
  • 文件管理
    • 创建失败时检查文件大小、路径与权限；删除失败时确认ID或URL是否正确

章节来源

结论​

基础设施API通过统一RPC前缀与清晰的接口职责，为配置、文件、日志与消息推送提供了标准化能力。结合完善的日志与监控体系，能够有效支撑系统的可观测性与可运维性。建议在生产环境合理配置WebSocket消息通道、实施日志清理策略，并持续优化文件存储与消息投递性能。

附录​

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答