146 lines
3.5 KiB
Markdown
146 lines
3.5 KiB
Markdown
# 统一上传接口
|
||
|
||
## 接口信息
|
||
|
||
- **接口名称**: 统一上传接口
|
||
- **接口路径**: /file/upload 或 /file/{storageType}/{bucketName}/upload
|
||
- **请求方法**: POST
|
||
- **模块归属**: file
|
||
- **版本号**: v1.0.0
|
||
- **创建日期**: 2026-01-18
|
||
- **最后更新**: 2026-01-18
|
||
|
||
## 功能描述
|
||
|
||
提供统一的文件上传接口，支持指定存储类型和存储桶，也可以使用默认存储。上传成功后返回文件访问 URL 和文件信息。
|
||
|
||
## 请求参数
|
||
|
||
### 路径参数
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例 |
|
||
|--------|------|------|------|------|
|
||
| storageType | String | 否 | 存储类型，不传则使用默认存储 | minio, local, aliyun-oss |
|
||
| bucketName | String | 否 | 存储桶名称，不传则使用默认存储桶 | primary, backup |
|
||
|
||
### 表单参数
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例 |
|
||
|--------|------|------|------|------|
|
||
| file | MultipartFile | 是 | 要上传的文件 | - |
|
||
|
||
## 响应数据
|
||
|
||
### 成功响应
|
||
|
||
**HTTP 状态码**: 200 OK
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"url": "https://example.com/files/upload/1234567890_test.jpg",
|
||
"info": {
|
||
"fileId": 1,
|
||
"fileName": "test.jpg",
|
||
"filePath": "upload/1234567890_test.jpg",
|
||
"fileSize": 102400,
|
||
"fileType": "jpg",
|
||
"storageType": "minio",
|
||
"createTime": "2026-01-18T10:00:00"
|
||
},
|
||
"fileName": "test.jpg"
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段名 | 类型 | 描述 | 示例 |
|
||
|--------|------|------|------|
|
||
| url | String | 文件访问 URL | https://example.com/files/upload/1234567890_test.jpg |
|
||
| info | Object | 文件详细信息对象 | - |
|
||
| fileName | String | 文件名 | test.jpg |
|
||
|
||
### 失败响应
|
||
|
||
**HTTP 状态码**: 500 Internal Server Error
|
||
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "上传失败: 存储空间不足",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 接口示例
|
||
|
||
### 请求示例
|
||
|
||
**使用默认存储**:
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8080/file/upload" \
|
||
-H "Authorization: Bearer [token]" \
|
||
-F "file=@/path/to/file.jpg"
|
||
```
|
||
|
||
**指定存储类型和存储桶**:
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8080/file/minio/primary/upload" \
|
||
-H "Authorization: Bearer [token]" \
|
||
-F "file=@/path/to/file.jpg"
|
||
```
|
||
|
||
### 响应示例
|
||
|
||
**成功**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"url": "https://minio.example.com/files/upload/1234567890_test.jpg",
|
||
"info": {
|
||
"fileId": 1,
|
||
"fileName": "test.jpg",
|
||
"filePath": "upload/1234567890_test.jpg",
|
||
"fileSize": 102400,
|
||
"fileType": "jpg",
|
||
"storageType": "minio",
|
||
"createTime": "2026-01-18T10:00:00"
|
||
},
|
||
"fileName": "test.jpg"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
- 文件为空时返回错误
|
||
- 存储空间不足时返回错误
|
||
- 存储类型或存储桶不存在时返回错误
|
||
- 文件大小超过限制时返回错误
|
||
|
||
## 注意事项
|
||
|
||
- 文件路径格式为：upload/{timestamp}_{originalFilename}
|
||
- 上传成功后会自动在数据库中创建文件记录
|
||
- 支持多种存储类型：local、minio、aliyun-oss 等
|
||
- 不指定存储类型时使用系统配置的默认存储
|
||
|
||
## 相关接口
|
||
|
||
- [获取存储渠道列表](./0001-client-list.md) - 获取可用的存储渠道
|
||
- [统一下载接口](./0003-download.md) - 下载已上传的文件
|
||
- [统一预览接口](./0004-preview.md) - 预览已上传的文件
|
||
|
||
## 实现细节
|
||
|
||
- 使用 `StorageService` 处理文件上传
|
||
- 文件信息使用 `SysFileInfo` 实体类存储
|
||
- 上传路径自动生成，包含时间戳避免文件名冲突
|
||
- 支持大文件上传，具体大小限制取决于存储类型配置
|