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

基础设施API

**本文引用的文件** - [ConfigApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java) - [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java) - [ConfigTypeEnum.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/config/ConfigTypeEnum.java) - [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java) - [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.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) - [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java) - [WebSocketSendReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/dto/WebSocketSendReqDTO.java) - [ApiConstants.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/ApiConstants.java) - [CodegenTemplateTypeEnum.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/codegen/CodegenTemplateTypeEnum.java)

目录

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

简介

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

• 系统配置管理：提供配置的增删改查、分页、导出Excel、按键取值等接口；明确配置分类与可见性控制。
• 文件上传下载：提供后端直传、前端直传（预签名）、文件创建、下载、删除与分页接口；说明文件类型、大小与存储策略。
• WebSocket消息推送：提供基于会话或用户维度的消息推送接口，支持消息类型与内容格式。
• 代码生成器API：支持根据数据库表结构生成前后端代码，包含模板类型枚举。

文档同时给出接口调用示例与错误处理说明，帮助开发者快速集成与排障。

项目结构

基础设施模块由“API接口层”和“服务端实现层”组成，API层通过OpenFeign声明远程调用接口，服务端实现层提供RESTful控制器与业务逻辑。

graph TB
subgraph "API 层"
A1["ConfigApi.java"]
A2["FileApi.java"]
A3["WebSocketSenderApi.java"]
A4["ApiConstants.java"]
A5["FileCreateReqDTO.java"]
A6["WebSocketSendReqDTO.java"]
A7["ConfigTypeEnum.java"]
A8["CodegenTemplateTypeEnum.java"]
end
subgraph "服务端实现层"
S1["ConfigController.java"]
S2["FileController.java"]
S3["WebSocketSenderApiImpl.java"]
end
A1 --> S1
A2 --> S2
A3 --> S3

图表来源

• ConfigApi.java
• FileApi.java
• WebSocketSenderApi.java
• ConfigController.java
• FileController.java
• WebSocketSenderApiImpl.java

章节来源

• ConfigApi.java
• FileApi.java
• WebSocketSenderApi.java
• ConfigController.java
• FileController.java
• WebSocketSenderApiImpl.java

核心组件

• 配置管理API：通过Feign接口暴露配置的键值查询能力，服务端提供完整的增删改查、分页与导出能力。
• 文件存储API：提供文件上传（后端直传/前端直传）、创建、下载、删除与分页接口；支持预签名URL用于前端直传。
• WebSocket消息推送API：提供REST风格的发送接口，支持按会话、按用户类型+用户ID、按用户类型三种推送方式。
• 代码生成器模板类型：定义单表、树表、主子表等模板类型，支撑代码生成器API。

章节来源

• ConfigApi.java
• ConfigController.java
• FileApi.java
• FileController.java
• WebSocketSenderApi.java
• WebSocketSenderApiImpl.java
• CodegenTemplateTypeEnum.java

架构总览

基础设施模块采用“API声明 + 控制器实现”的分层架构。API层通过OpenFeign声明远程调用接口，服务端实现层提供RESTful控制器，统一在统一前缀下暴露HTTP接口。

graph TB
C1["ConfigController<br/>GET/POST/PUT/DELETE /infra/config/*"] --> SvcC["ConfigService"]
F1["FileController<br/>POST/GET /infra/file/*"] --> SvcF["FileService"]
W1["WebSocketSenderApiImpl<br/>POST /infra/websocket/send"] --> WS["WebSocketMessageSender"]
subgraph "API 声明"
A1["ConfigApi"]
A2["FileApi"]
A3["WebSocketSenderApi"]
end
A1 --> C1
A2 --> F1
A3 --> W1

图表来源

• ConfigController.java
• FileController.java
• WebSocketSenderApiImpl.java
• ConfigApi.java
• FileApi.java
• WebSocketSenderApi.java

详细组件分析

配置管理API

• 接口范围
  • 创建配置：POST /infra/config/create
  • 修改配置：PUT /infra/config/update
  • 删除配置：DELETE /infra/config/delete?id=...
  • 批量删除：DELETE /infra/config/delete-list?ids=...
  • 查询配置：GET /infra/config/get?id=...
  • 键值查询：GET /infra/config/get-value-by-key?key=...
  • 分页查询：GET /infra/config/page
  • 导出Excel：GET /infra/config/export-excel
• 关键行为
  • 键值查询对不可见配置进行保护，若不可见则抛出错误。
  • 分页与导出支持复杂筛选条件。
• 配置分类
  • 系统配置与自定义配置两类，便于区分权限与作用域。
• 生效机制
  • 本节未发现显式的“立即生效”接口；键值查询接口返回当前值，建议结合缓存或配置中心实现热更新。

sequenceDiagram
participant Client as "客户端"
participant Ctrl as "ConfigController"
participant Svc as "ConfigService"
Client->>Ctrl : GET /infra/config/get-value-by-key?key=...
Ctrl->>Svc : getConfigByKey(key)
Svc-->>Ctrl : ConfigDO
alt 不可见配置
Ctrl-->>Client : 错误响应
else 可见配置
Ctrl-->>Client : 返回value
end

图表来源

• ConfigController.java

章节来源

• ConfigController.java
• ConfigApi.java
• ConfigTypeEnum.java

文件上传下载API

• 接口范围
  • 后端直传：POST /infra/file/upload（multipart）
  • 前端直传预签名URL：GET /infra/file/presigned-url?name=...&directory=...
  • 创建文件记录：POST /infra/file/create（配合前端直传）
  • 下载文件：GET /infra/file/{configId}/get/**（透传路径）
  • 删除文件：DELETE /infra/file/delete?id=...
  • 批量删除：DELETE /infra/file/delete-list?ids=...
  • 查询文件：GET /infra/file/get?id=...
  • 分页查询：GET /infra/file/page
• 文件类型与大小
  • 服务端直传：从上传文件中读取原始名称与MIME类型，未见显式大小限制。
  • 前端直传：通过预签名URL生成上传凭证，具体大小限制取决于对象存储策略。
• 存储策略
  • 支持“后端直传”和“前端直传”两种模式；前端直传需配合预签名URL接口使用。
  • 文件创建接口可记录已上传文件信息，便于后续管理与下载。

sequenceDiagram
participant Client as "客户端"
participant Ctrl as "FileController"
participant Svc as "FileService"
Client->>Ctrl : POST /infra/file/upload
Ctrl->>Svc : createFile(content, name, directory, type)
Svc-->>Ctrl : 返回访问路径
Ctrl-->>Client : 成功响应
Client->>Ctrl : GET /infra/file/presigned-url
Ctrl->>Svc : presignPutUrl(name, directory)
Svc-->>Ctrl : 返回预签名URL
Ctrl-->>Client : 预签名URL
Client->>Ctrl : POST /infra/file/create
Ctrl->>Svc : createFile(createReqDTO)
Svc-->>Ctrl : 返回文件ID
Ctrl-->>Client : 成功响应

图表来源

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

章节来源

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

WebSocket消息推送API

• 接口范围
  • 发送消息：POST /infra/websocket/send
• 推送范围
  • 按会话ID推送：指定sessionId
  • 按用户类型+用户ID推送：指定userType与userId
  • 按用户类型推送：指定userType（广播到该类型所有在线会话）
• 消息格式
  • 消息类型与内容均为字符串，建议使用JSON格式承载业务数据。
• 消息持久化
  • 本节未发现消息持久化接口；如需持久化，可在业务侧自行实现。

sequenceDiagram
participant Caller as "调用方"
participant API as "WebSocketSenderApi"
participant Impl as "WebSocketSenderApiImpl"
participant Sender as "WebSocketMessageSender"
Caller->>API : POST /infra/websocket/send
API->>Impl : send(message)
alt 指定sessionId
Impl->>Sender : send(sessionId, messageType, messageContent)
else 指定userType与userId
Impl->>Sender : send(userType, userId, messageType, messageContent)
else 仅指定userType
Impl->>Sender : send(userType, messageType, messageContent)
end
Impl-->>Caller : 成功响应

图表来源

• WebSocketSenderApi.java
• WebSocketSenderApiImpl.java
• WebSocketSendReqDTO.java

章节来源

• WebSocketSenderApi.java
• WebSocketSenderApiImpl.java
• WebSocketSendReqDTO.java

代码生成器API

• 模板类型
  • 单表（增删改查）
  • 树表（增删改查）
  • 主子表：主表普通/ERP/内嵌模式，子表
• 使用场景
  • 根据数据库表结构生成前后端代码，提升开发效率。
• 适用范围
  • 本节提供模板类型枚举，具体生成流程在上层模块或工具链中实现。

章节来源

• CodegenTemplateTypeEnum.java

依赖关系分析

• 统一前缀与版本
  • 所有接口均以统一前缀与版本号组合，便于网关路由与版本管理。
• 接口命名与路径
  • 配置：/infra/config/*
  • 文件：/infra/file/*
  • WebSocket：/infra/websocket/*
• 权限控制
  • 管理后台接口普遍使用权限注解进行授权校验。

graph LR
AC["ApiConstants.PREFIX"] --> P1["/infra/config/*"]
AC --> P2["/infra/file/*"]
AC --> P3["/infra/websocket/*"]
AC --> V["VERSION 1.0.0"]

图表来源

• ApiConstants.java

章节来源

• ApiConstants.java

性能考量

• 文件上传
  • 建议对大文件采用分片上传与断点续传，减少网络波动影响。
  • 前端直传模式可利用对象存储的并发上传能力，提升吞吐。
• 配置查询
  • 键值查询建议结合本地缓存，降低数据库压力。
• WebSocket
  • 广播推送应避免过大的消息体，建议拆分为多个小消息或压缩传输。

故障排查指南

• 配置键值查询失败
  • 若返回空值，确认键是否存在；若抛出错误，确认配置是否可见。
• 文件下载404
  • 确认路径编码与解码正确，检查文件是否存在于存储系统。
• WebSocket推送无响应
  • 确认目标会话或用户是否在线；检查消息类型与内容格式是否符合预期。

章节来源

• ConfigController.java
• FileController.java
• WebSocketSenderApiImpl.java

结论

基础设施模块提供了完善的配置管理、文件存储与WebSocket消息推送能力，接口清晰、职责明确。建议在生产环境中结合缓存与对象存储优化性能，并完善消息持久化与错误监控体系。

附录

• 接口调用示例（路径与方法）
  • 配置管理
    • 创建：POST /infra/config/create
    • 更新：PUT /infra/config/update
    • 删除：DELETE /infra/config/delete?id=1
    • 批量删除：DELETE /infra/config/delete-list?ids=1,2
    • 查询：GET /infra/config/get?id=1
    • 键值查询：GET /infra/config/get-value-by-key?key=...
    • 分页：GET /infra/config/page
    • 导出：GET /infra/config/export-excel
  • 文件存储
    • 后端直传：POST /infra/file/upload（multipart）
    • 预签名URL：GET /infra/file/presigned-url?name=...&directory=...
    • 创建文件：POST /infra/file/create
    • 下载：GET /infra/file/{configId}/get/**（透传路径）
    • 删除：DELETE /infra/file/delete?id=1
    • 批量删除：DELETE /infra/file/delete-list?ids=1,2
    • 查询：GET /infra/file/get?id=1
    • 分页：GET /infra/file/page
  • WebSocket推送
    • 发送：POST /infra/websocket/send