116 lines
2.8 KiB
Markdown
116 lines
2.8 KiB
Markdown
|
# 初始化分片上传
|
|||
|
|
|
|||
|
|
## 接口信息
|
|||
|
|
|
|||
|
|
- **接口名称**: 初始化分片上传
|
|||
|
|
- **接口路径**: /file/initUpload
|
|||
|
|
- **请求方法**: POST
|
|||
|
|
- **模块归属**: file
|
|||
|
|
- **版本号**: v1.0.0
|
|||
|
|
- **创建日期**: 2026-01-18
|
|||
|
|
- **最后更新**: 2026-01-18
|
|||
|
|
|
|||
|
|
## 功能描述
|
|||
|
|
|
|||
|
|
初始化分片上传，生成上传 ID 和文件路径，用于后续的分片上传操作。支持大文件分片上传，提高上传效率和可靠性。
|
|||
|
|
|
|||
|
|
## 请求参数
|
|||
|
|
|
|||
|
|
### 表单参数
|
|||
|
|
|
|||
|
|
| 参数名 | 类型 | 必填 | 描述 | 示例 |
|
|||
|
|
|--------|------|------|------|------|
|
|||
|
|
| fileName | String | 是 | 文件名 | large-file.zip |
|
|||
|
|
| fileSize | Long | 是 | 文件大小（字节） | 1073741824 |
|
|||
|
|
|
|||
|
|
## 响应数据
|
|||
|
|
|
|||
|
|
### 成功响应
|
|||
|
|
|
|||
|
|
**HTTP 状态码**: 200 OK
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "操作成功",
|
|||
|
|
"data": {
|
|||
|
|
"uploadId": "1234567890abcdef",
|
|||
|
|
"filePath": "/upload/2026/01/18/1234567890_large-file.zip",
|
|||
|
|
"fileName": "large-file.zip"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
| 字段名 | 类型 | 描述 | 示例 |
|
|||
|
|
|--------|------|------|------|
|
|||
|
|
| uploadId | String | 上传 ID，用于后续分片上传和合并 | 1234567890abcdef |
|
|||
|
|
| filePath | String | 文件存储路径 | /upload/2026/01/18/1234567890_large-file.zip |
|
|||
|
|
| fileName | String | 文件名 | large-file.zip |
|
|||
|
|
|
|||
|
|
### 失败响应
|
|||
|
|
|
|||
|
|
**HTTP 状态码**: 500 Internal Server Error
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 500,
|
|||
|
|
"message": "文件名或文件大小不能为空",
|
|||
|
|
"data": null
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 接口示例
|
|||
|
|
|
|||
|
|
### 请求示例
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -X POST "http://localhost:8080/file/initUpload" \
|
|||
|
|
-H "Authorization: Bearer [token]" \
|
|||
|
|
-F "fileName=large-file.zip" \
|
|||
|
|
-F "fileSize=1073741824"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 响应示例
|
|||
|
|
|
|||
|
|
**成功**:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "操作成功",
|
|||
|
|
"data": {
|
|||
|
|
"uploadId": "1234567890abcdef",
|
|||
|
|
"filePath": "/upload/2026/01/18/1234567890_large-file.zip",
|
|||
|
|
"fileName": "large-file.zip"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 错误处理
|
|||
|
|
|
|||
|
|
- 文件名为空时返回错误
|
|||
|
|
- 文件大小为空或小于等于 0 时返回错误
|
|||
|
|
- 初始化上传失败时返回错误
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
- 文件路径格式为：/upload/{yyyy}/{MM}/{dd}/{timestamp}_{fileName}
|
|||
|
|
- 使用系统配置的默认存储
|
|||
|
|
- 上传 ID 用于后续的分片上传和合并操作
|
|||
|
|
- 分片上传适用于大文件（通常大于 100MB）
|
|||
|
|
- 初始化成功后需要调用上传分片接口上传各个分片
|
|||
|
|
|
|||
|
|
## 相关接口
|
|||
|
|
|
|||
|
|
- [上传文件分片](./0007-upload-chunk.md) - 上传文件分片
|
|||
|
|
- [完成分片上传](./0008-complete-upload.md) - 完成分片上传并合并文件
|
|||
|
|
- [统一上传接口](./0002-upload.md) - 普通文件上传（非分片）
|
|||
|
|
|
|||
|
|
## 实现细节
|
|||
|
|
|
|||
|
|
- 使用 `StorageService.initMultipartUpload()` 初始化分片上传
|
|||
|
|
- 文件路径包含日期目录：yyyy/MM/dd
|
|||
|
|
- 文件名前缀使用时间戳避免冲突
|
|||
|
|
- 使用系统配置的默认存储桶
|
|||
|
|
- 返回的 uploadId 必须妥善保存，用于后续操作
|