aiot-platform-cloud/.qoder/repowiki/zh/content/API接口文档/业务模块API/基础设施API.md

基础设施API

**本文引用的文件** - [ApiConstants.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/ApiConstants.java) - [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java) - [FileCreateReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/dto/FileCreateReqDTO.java) - [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java) - [WebSocketSendReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/dto/WebSocketSendReqDTO.java) - [ConfigApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java) - [CodegenTemplateTypeEnum.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/codegen/CodegenTemplateTypeEnum.java) - [ConfigTypeEnum.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/config/ConfigTypeEnum.java) - [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java) - [FileConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileConfigController.java) - [ApiAccessLogController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/logger/ApiAccessLogController.java) - [ApiErrorLogController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/logger/ApiErrorLogController.java) - [RedisController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/redis/RedisController.java) - [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java) - [CodegenController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/codegen/CodegenController.java) - [InfraServerApplication.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/InfraServerApplication.java)

目录

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

简介

本文件面向基础设施模块的API接口文档，覆盖以下能力域：

• 文件管理：文件上传、预签名URL生成、本地/云存储集成、文件预览与删除（通过控制器与DTO定义体现）
• 代码生成：数据库表结构生成、前后端代码模板生成、模板类型与场景枚举
• WebSocket通信：消息发送、对象序列化便捷方法
• 定时任务：模块内作业与调度（通过作业包与配置体现）
• 系统配置管理：参数配置查询、配置类型枚举
• 日志管理：访问日志与错误日志分页查询
• 基础设施监控：Redis监控接口
• 使用示例与最佳实践：结合DTO与控制器请求体说明

项目结构

基础设施模块采用“API接口 + 服务端控制器”的分层设计：

• API接口层：定义对外暴露的Feign接口与DTO，统一服务名与前缀
• 服务端控制器层：实现具体业务逻辑，提供RESTful接口
• 枚举与常量：集中管理模板类型、配置类型、API前缀等

graph TB
subgraph "API接口层"
FA["FileApi"]
WSA["WebSocketSenderApi"]
CA["ConfigApi"]
end
subgraph "服务端控制器层"
FC["FileController"]
FCC["FileConfigController"]
ACC["ApiAccessLogController"]
AEC["ApiErrorLogController"]
RC["RedisController"]
CC["ConfigController"]
CGC["CodegenController"]
end
subgraph "DTO与枚举"
FCR["FileCreateReqDTO"]
WSR["WebSocketSendReqDTO"]
CTT["CodegenTemplateTypeEnum"]
CTY["ConfigTypeEnum"]
AC["ApiConstants"]
end
FA --> FC
WSA --> RC
CA --> CC
FC --> FCR
WSA --> WSR
CC --> CTY
CGC --> CTT
FC --> AC
WSA --> AC
CA --> AC

图表来源

• FileApi.java
• WebSocketSenderApi.java
• ConfigApi.java
• FileController.java
• FileConfigController.java
• ApiAccessLogController.java
• ApiErrorLogController.java
• RedisController.java
• ConfigController.java
• CodegenController.java
• FileCreateReqDTO.java
• WebSocketSendReqDTO.java
• CodegenTemplateTypeEnum.java
• ConfigTypeEnum.java
• ApiConstants.java

章节来源

• InfraServerApplication.java

核心组件

• API常量与前缀：统一服务名与API前缀，便于跨模块调用
• 文件API：文件上传、预签名URL生成
• WebSocket发送器：消息发送与对象序列化便捷方法
• 配置API：按Key查询配置值
• 代码生成枚举：模板类型与场景分类
• 配置类型枚举：系统配置与自定义配置

章节来源

• ApiConstants.java
• FileApi.java
• WebSocketSenderApi.java
• ConfigApi.java
• CodegenTemplateTypeEnum.java
• ConfigTypeEnum.java

架构总览

基础设施模块通过Feign接口向其他模块暴露能力，服务端控制器实现具体业务，统一前缀与版本便于网关路由与鉴权。

sequenceDiagram
participant Caller as "调用方"
participant Feign as "FileApi/ConfigApi"
participant Ctrl as "FileController/ConfigController"
participant Biz as "业务服务"
participant Store as "存储(本地/云)"
participant Resp as "CommonResult"
Caller->>Feign : "POST /infra/v1/file/create"
Feign->>Ctrl : "转发请求"
Ctrl->>Biz : "保存文件/生成预签名URL"
Biz->>Store : "写入/读取"
Store-->>Biz : "返回访问路径/预签名URL"
Biz-->>Ctrl : "结果数据"
Ctrl-->>Resp : "封装CommonResult"
Resp-->>Feign : "返回响应"
Feign-->>Caller : "响应结果"

图表来源

• FileApi.java
• ConfigApi.java
• FileController.java
• ConfigController.java

详细组件分析

文件管理API

• 接口目标：提供文件上传与预签名URL生成能力
• 关键字段：
  • FileCreateReqDTO：name、directory、type、content
  • 预签名URL：url、expirationSeconds
• 默认重载方法：支持便捷传参
• 控制器职责：接收请求、调用业务服务、返回CommonResult

sequenceDiagram
participant Client as "客户端"
participant API as "FileApi"
participant Ctrl as "FileController"
participant Svc as "FileService"
participant Store as "存储"
Client->>API : "POST /infra/v1/file/create"
API->>Ctrl : "createFile(FileCreateReqDTO)"
Ctrl->>Svc : "saveFile(dto)"
Svc->>Store : "写入文件"
Store-->>Svc : "返回访问路径"
Svc-->>Ctrl : "访问路径"
Ctrl-->>Client : "CommonResult<String>"

图表来源

• FileApi.java
• FileCreateReqDTO.java
• FileController.java

章节来源

• FileApi.java
• FileCreateReqDTO.java

WebSocket消息推送API

• 接口目标：向指定用户或Session发送消息
• 关键字段：sessionId、userId、userType、messageType、messageContent
• 便捷方法：sendObject支持对象自动序列化为JSON

sequenceDiagram
participant Caller as "调用方"
participant WSAPI as "WebSocketSenderApi"
participant Ctrl as "WebSocketController"
participant Sender as "WebSocketMessageSender"
participant Client as "客户端"
Caller->>WSAPI : "POST /infra/v1/websocket/send"
WSAPI->>Ctrl : "send(WebSocketSendReqDTO)"
Ctrl->>Sender : "sendMessage(dto)"
Sender-->>Client : "推送消息"
Sender-->>Ctrl : "发送结果"
Ctrl-->>Caller : "CommonResult<Boolean>"

图表来源

• WebSocketSenderApi.java
• WebSocketSendReqDTO.java

章节来源

• WebSocketSenderApi.java
• WebSocketSendReqDTO.java

系统配置管理API

• 接口目标：按Key查询配置值
• 场景：动态配置下发、开关控制

sequenceDiagram
participant Client as "客户端"
participant API as "ConfigApi"
participant Ctrl as "ConfigController"
participant Svc as "ConfigService"
Client->>API : "GET /infra/v1/config/get-value-by-key?key=..."
API->>Ctrl : "getConfigValueByKey(key)"
Ctrl->>Svc : "查询配置"
Svc-->>Ctrl : "配置值"
Ctrl-->>Client : "CommonResult<String>"

图表来源

• ConfigApi.java
• ConfigController.java

章节来源

• ConfigApi.java
• ConfigTypeEnum.java

代码生成API

• 接口目标：基于数据库表结构生成前后端代码
• 模板类型：单表、树表、主子表（普通/ERP/内嵌）、子表
• 使用建议：先选择模板类型，再配置表与列信息，最后生成与预览

flowchart TD
Start(["开始"]) --> ChooseTpl["选择模板类型<br/>CodegenTemplateTypeEnum"]
ChooseTpl --> Configure["配置表与列信息"]
Configure --> Generate["生成代码"]
Generate --> Preview["预览结果"]
Preview --> Download["下载产物"]
Download --> End(["结束"])

图表来源

• CodegenTemplateTypeEnum.java
• CodegenController.java

章节来源

• CodegenTemplateTypeEnum.java
• CodegenController.java

日志管理API

• 访问日志：分页查询API访问记录
• 错误日志：分页查询API错误记录与处理状态

sequenceDiagram
participant Admin as "管理员"
participant AccessCtrl as "ApiAccessLogController"
participant ErrorCtrl as "ApiErrorLogController"
participant Svc as "日志服务"
Admin->>AccessCtrl : "分页查询访问日志"
AccessCtrl->>Svc : "查询访问日志"
Svc-->>AccessCtrl : "分页结果"
AccessCtrl-->>Admin : "CommonResult<PageResult>"
Admin->>ErrorCtrl : "分页查询错误日志"
ErrorCtrl->>Svc : "查询错误日志"
Svc-->>ErrorCtrl : "分页结果"
ErrorCtrl-->>Admin : "CommonResult<PageResult>"

图表来源

• ApiAccessLogController.java
• ApiErrorLogController.java

章节来源

• ApiAccessLogController.java
• ApiErrorLogController.java

基础设施监控API

• Redis监控：获取Redis运行指标（如内存、连接数等）

sequenceDiagram
participant Ops as "运维人员"
participant RedisCtrl as "RedisController"
participant Redis as "Redis实例"
Ops->>RedisCtrl : "查询Redis监控指标"
RedisCtrl->>Redis : "INFO/STATS"
Redis-->>RedisCtrl : "指标数据"
RedisCtrl-->>Ops : "CommonResult<RedisMonitorRespVO>"

图表来源

• RedisController.java

章节来源

• RedisController.java

依赖关系分析

• 统一前缀：所有接口均以 /infra/v1 前缀开头，便于网关路由与权限控制
• 服务名：infra-server，确保Feign调用正确路由
• DTO约束：请求参数通过注解进行非空与格式校验
• 枚举约束：模板类型与配置类型统一管理，避免魔法值

graph LR
AC["ApiConstants"] --> FA["FileApi"]
AC --> WSA["WebSocketSenderApi"]
AC --> CA["ConfigApi"]
FA --> FCR["FileCreateReqDTO"]
WSA --> WSR["WebSocketSendReqDTO"]
CC["ConfigController"] --> CTY["ConfigTypeEnum"]
CGC["CodegenController"] --> CTT["CodegenTemplateTypeEnum"]

图表来源

• ApiConstants.java
• FileApi.java
• WebSocketSenderApi.java
• ConfigApi.java
• FileCreateReqDTO.java
• WebSocketSendReqDTO.java
• ConfigTypeEnum.java
• CodegenTemplateTypeEnum.java

章节来源

• ApiConstants.java

性能考量

• 文件上传：建议对大文件采用分片上传与断点续传策略；预签名URL缩短直传路径
• WebSocket：合理设置心跳与重连策略，避免长连接占用资源
• 日志查询：分页查询与索引优化，避免全表扫描
• Redis监控：定期采样关键指标，避免频繁高开销命令

故障排查指南

• 文件上传失败
  • 检查content是否为空、MIME类型是否正确
  • 查看存储服务可用性与权限
• 预签名URL失效
  • 校验url与过期时间参数
  • 确认存储服务签名算法与有效期配置
• WebSocket消息未达
  • 校验sessionId或userId/userType是否有效
  • 检查消息类型与内容格式
• 配置查询为空
  • 确认key是否存在且未被删除
  • 检查配置类型与作用域
• 日志查询无数据
  • 校验查询条件与时间范围
  • 确认日志采集与落库流程正常

章节来源

• FileCreateReqDTO.java
• WebSocketSendReqDTO.java
• ConfigApi.java

结论

基础设施模块通过统一的API前缀与服务名，提供了文件管理、WebSocket推送、配置查询、代码生成、日志与监控等核心能力。建议在生产环境中结合分片上传、预签名URL、心跳监控与分页查询等最佳实践，确保系统的稳定性与可维护性。

附录

• 使用示例（路径指引）
  • 文件上传：POST /infra/v1/file/create，请求体参考 FileCreateReqDTO.java
  • 预签名URL：GET /infra/v1/file/presigned-url?url=...&expirationSeconds=...
  • WebSocket发送：POST /infra/v1/websocket/send，请求体参考 WebSocketSendReqDTO.java
  • 配置查询：GET /infra/v1/config/get-value-by-key?key=...
  • 代码生成：参考 CodegenController.java
  • 日志查询：访问 ApiAccessLogController.java 与 ApiErrorLogController.java
  • Redis监控：参考 RedisController.java