75 lines
2.8 KiB
Markdown
75 lines
2.8 KiB
Markdown
# FileController 接口文档
|
||
|
||
## 概述
|
||
|
||
FileController 提供统一的文件存储服务接口，支持多种存储类型（local、minio、aliyun-oss 等），包括文件上传、下载、预览、分片上传等功能。
|
||
|
||
## 接口列表
|
||
|
||
### 基础接口
|
||
|
||
| 接口名称 | 接口路径 | 请求方法 | 说明 |
|
||
|----------|----------|----------|------|
|
||
| 获取所有可用存储渠道及其client列表 | /file/client-list | GET | 获取系统可用的存储渠道列表 |
|
||
| 统一上传接口 | /file/upload<br>/file/{storageType}/{bucketName}/upload | POST | 上传文件到指定存储 |
|
||
| 统一下载接口 | /file/download<br>/file/{storageType}/{bucketName}/download | GET | 从指定存储下载文件 |
|
||
| 统一预览接口 | /file/preview<br>/file/{storageType}/{bucketName}/preview | GET | 在线预览文件（支持匿名访问） |
|
||
| 本地资源通用下载 | /file/resource | GET | 下载本地资源文件（支持匿名访问） |
|
||
|
||
### 分片上传接口
|
||
|
||
| 接口名称 | 接口路径 | 请求方法 | 说明 |
|
||
|----------|----------|----------|------|
|
||
| 初始化分片上传 | /file/initUpload | POST | 初始化分片上传，获取 uploadId |
|
||
| 上传文件分片 | /file/uploadChunk | POST | 上传文件的一个分片 |
|
||
| 完成分片上传并合并文件 | /file/completeUpload | POST | 完成分片上传并合并文件 |
|
||
|
||
## 存储类型
|
||
|
||
系统支持以下存储类型：
|
||
|
||
- **local**: 本地文件系统存储
|
||
- **minio**: MinIO 对象存储
|
||
- **aliyun-oss**: 阿里云 OSS 对象存储
|
||
|
||
## 使用流程
|
||
|
||
### 普通文件上传流程
|
||
|
||
1. 调用 [获取存储渠道列表](./0001-client-list.md) 获取可用的存储渠道
|
||
2. 调用 [统一上传接口](./0002-upload.md) 上传文件
|
||
3. 使用返回的 URL 进行文件访问
|
||
|
||
### 分片上传流程
|
||
|
||
1. 调用 [初始化分片上传](./0006-init-upload.md) 获取 uploadId 和文件路径
|
||
2. 循环调用 [上传文件分片](./0007-upload-chunk.md) 上传所有分片
|
||
3. 调用 [完成分片上传](./0008-complete-upload.md) 合并所有分片
|
||
|
||
### 文件下载流程
|
||
|
||
1. 调用 [统一下载接口](./0003-download.md) 下载文件
|
||
2. 浏览器会自动触发文件下载
|
||
|
||
### 文件预览流程
|
||
|
||
1. 调用 [统一预览接口](./0004-preview.md) 预览文件
|
||
2. 浏览器会根据文件类型进行在线预览
|
||
|
||
## 权限说明
|
||
|
||
- 大部分接口需要认证（需要携带 Authorization 头）
|
||
- [统一预览接口](./0004-preview.md) 和 [本地资源通用下载](./0005-resource.md) 支持匿名访问
|
||
|
||
## 注意事项
|
||
|
||
1. 文件路径格式为：upload/{timestamp}_{originalFilename}
|
||
2. 分片上传适用于大文件（通常大于 100MB）
|
||
3. 分片序号必须从 1 开始，连续递增
|
||
4. 需要妥善保存 uploadId 和所有分片的 ETag
|
||
5. 预览接口会自动识别文件类型
|
||
|
||
## 相关文档
|
||
|
||
- [SysFileInfoController 接口文档](../SysFileInfoController/index.md) - 文件信息管理接口
|