# 基础设施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