333 lines
19 KiB
Markdown
333 lines
19 KiB
Markdown
# 基础设施API
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件面向基础设施模块的API接口文档，覆盖以下能力：
|
||
- 系统配置管理：提供配置的增删改查、分页、导出Excel、按键取值等接口；明确配置分类与可见性控制。
|
||
- 文件上传下载：提供后端直传、前端直传（预签名）、文件创建、下载、删除与分页接口；说明文件类型、大小与存储策略。
|
||
- WebSocket消息推送：提供基于会话或用户维度的消息推送接口，支持消息类型与内容格式。
|
||
- 代码生成器API：支持根据数据库表结构生成前后端代码，包含模板类型枚举。
|
||
|
||
文档同时给出接口调用示例与错误处理说明，帮助开发者快速集成与排障。
|
||
|
||
## 项目结构
|
||
基础设施模块由“API接口层”和“服务端实现层”组成，API层通过OpenFeign声明远程调用接口，服务端实现层提供RESTful控制器与业务逻辑。
|
||
|
||
```mermaid
|
||
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](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java#L1-L22)
|
||
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java#L1-L74)
|
||
- [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java#L1-L33)
|
||
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L1-L118)
|
||
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L1-L138)
|
||
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L1-L36)
|
||
|
||
章节来源
|
||
- [ConfigApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java#L1-L22)
|
||
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java#L1-L74)
|
||
- [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java#L1-L33)
|
||
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L1-L118)
|
||
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L1-L138)
|
||
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L1-L36)
|
||
|
||
## 核心组件
|
||
- 配置管理API：通过Feign接口暴露配置的键值查询能力，服务端提供完整的增删改查、分页与导出能力。
|
||
- 文件存储API：提供文件上传（后端直传/前端直传）、创建、下载、删除与分页接口；支持预签名URL用于前端直传。
|
||
- WebSocket消息推送API：提供REST风格的发送接口，支持按会话、按用户类型+用户ID、按用户类型三种推送方式。
|
||
- 代码生成器模板类型：定义单表、树表、主子表等模板类型，支撑代码生成器API。
|
||
|
||
章节来源
|
||
- [ConfigApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java#L1-L22)
|
||
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L1-L118)
|
||
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java#L1-L74)
|
||
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L1-L138)
|
||
- [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java#L1-L33)
|
||
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L1-L36)
|
||
- [CodegenTemplateTypeEnum.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/codegen/CodegenTemplateTypeEnum.java#L1-L54)
|
||
|
||
## 架构总览
|
||
基础设施模块采用“API声明 + 控制器实现”的分层架构。API层通过OpenFeign声明远程调用接口，服务端实现层提供RESTful控制器，统一在统一前缀下暴露HTTP接口。
|
||
|
||
```mermaid
|
||
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](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L32-L118)
|
||
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L36-L138)
|
||
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L14-L36)
|
||
- [ConfigApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java#L11-L21)
|
||
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java#L16-L73)
|
||
- [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java#L15-L33)
|
||
|
||
## 详细组件分析
|
||
|
||
### 配置管理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
|
||
- 关键行为
|
||
- 键值查询对不可见配置进行保护，若不可见则抛出错误。
|
||
- 分页与导出支持复杂筛选条件。
|
||
- 配置分类
|
||
- 系统配置与自定义配置两类，便于区分权限与作用域。
|
||
- 生效机制
|
||
- 本节未发现显式的“立即生效”接口；键值查询接口返回当前值，建议结合缓存或配置中心实现热更新。
|
||
|
||
```mermaid
|
||
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](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L82-L94)
|
||
|
||
章节来源
|
||
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L32-L118)
|
||
- [ConfigApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java#L11-L21)
|
||
- [ConfigTypeEnum.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/config/ConfigTypeEnum.java#L1-L22)
|
||
|
||
### 文件上传下载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接口使用。
|
||
- 文件创建接口可记录已上传文件信息，便于后续管理与下载。
|
||
|
||
```mermaid
|
||
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](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L46-L73)
|
||
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java#L57-L73)
|
||
- [FileCreateReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/dto/FileCreateReqDTO.java#L1-L26)
|
||
|
||
章节来源
|
||
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L36-L138)
|
||
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java#L16-L73)
|
||
- [FileCreateReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/dto/FileCreateReqDTO.java#L1-L26)
|
||
|
||
### WebSocket消息推送API
|
||
- 接口范围
|
||
- 发送消息：POST /infra/websocket/send
|
||
- 推送范围
|
||
- 按会话ID推送：指定sessionId
|
||
- 按用户类型+用户ID推送：指定userType与userId
|
||
- 按用户类型推送：指定userType（广播到该类型所有在线会话）
|
||
- 消息格式
|
||
- 消息类型与内容均为字符串，建议使用JSON格式承载业务数据。
|
||
- 消息持久化
|
||
- 本节未发现消息持久化接口；如需持久化，可在业务侧自行实现。
|
||
|
||
```mermaid
|
||
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](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java#L15-L33)
|
||
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L14-L36)
|
||
- [WebSocketSendReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/dto/WebSocketSendReqDTO.java#L1-L26)
|
||
|
||
章节来源
|
||
- [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java#L1-L33)
|
||
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L1-L36)
|
||
- [WebSocketSendReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/dto/WebSocketSendReqDTO.java#L1-L26)
|
||
|
||
### 代码生成器API
|
||
- 模板类型
|
||
- 单表（增删改查）
|
||
- 树表（增删改查）
|
||
- 主子表：主表普通/ERP/内嵌模式，子表
|
||
- 使用场景
|
||
- 根据数据库表结构生成前后端代码，提升开发效率。
|
||
- 适用范围
|
||
- 本节提供模板类型枚举，具体生成流程在上层模块或工具链中实现。
|
||
|
||
章节来源
|
||
- [CodegenTemplateTypeEnum.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/codegen/CodegenTemplateTypeEnum.java#L1-L54)
|
||
|
||
## 依赖关系分析
|
||
- 统一前缀与版本
|
||
- 所有接口均以统一前缀与版本号组合，便于网关路由与版本管理。
|
||
- 接口命名与路径
|
||
- 配置：/infra/config/*
|
||
- 文件：/infra/file/*
|
||
- WebSocket：/infra/websocket/*
|
||
- 权限控制
|
||
- 管理后台接口普遍使用权限注解进行授权校验。
|
||
|
||
```mermaid
|
||
graph LR
|
||
AC["ApiConstants.PREFIX"] --> P1["/infra/config/*"]
|
||
AC --> P2["/infra/file/*"]
|
||
AC --> P3["/infra/websocket/*"]
|
||
AC --> V["VERSION 1.0.0"]
|
||
```
|
||
|
||
图表来源
|
||
- [ApiConstants.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/ApiConstants.java#L10-L23)
|
||
|
||
章节来源
|
||
- [ApiConstants.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/ApiConstants.java#L1-L24)
|
||
|
||
## 性能考量
|
||
- 文件上传
|
||
- 建议对大文件采用分片上传与断点续传，减少网络波动影响。
|
||
- 前端直传模式可利用对象存储的并发上传能力，提升吞吐。
|
||
- 配置查询
|
||
- 键值查询建议结合本地缓存，降低数据库压力。
|
||
- WebSocket
|
||
- 广播推送应避免过大的消息体，建议拆分为多个小消息或压缩传输。
|
||
|
||
## 故障排查指南
|
||
- 配置键值查询失败
|
||
- 若返回空值，确认键是否存在；若抛出错误，确认配置是否可见。
|
||
- 文件下载404
|
||
- 确认路径编码与解码正确，检查文件是否存在于存储系统。
|
||
- WebSocket推送无响应
|
||
- 确认目标会话或用户是否在线；检查消息类型与内容格式是否符合预期。
|
||
|
||
章节来源
|
||
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L82-L94)
|
||
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L101-L127)
|
||
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L21-L34)
|
||
|
||
## 结论
|
||
基础设施模块提供了完善的配置管理、文件存储与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 |