128 lines
3.0 KiB
Markdown
128 lines
3.0 KiB
Markdown
|
# 上传文件分片
|
|||
|
|
|
|||
|
|
## 接口信息
|
|||
|
|
|
|||
|
|
- **接口名称**: 上传文件分片
|
|||
|
|
- **接口路径**: /file/uploadChunk
|
|||
|
|
- **请求方法**: POST
|
|||
|
|
- **模块归属**: file
|
|||
|
|
- **版本号**: v1.0.0
|
|||
|
|
- **创建日期**: 2026-01-18
|
|||
|
|
- **最后更新**: 2026-01-18
|
|||
|
|
|
|||
|
|
## 功能描述
|
|||
|
|
|
|||
|
|
上传文件的一个分片，返回分片的 ETag。需要先调用初始化分片上传接口获取 uploadId，然后逐个上传文件分片。
|
|||
|
|
|
|||
|
|
## 请求参数
|
|||
|
|
|
|||
|
|
### 表单参数
|
|||
|
|
|
|||
|
|
| 参数名 | 类型 | 必填 | 描述 | 示例 |
|
|||
|
|
|--------|------|------|------|------|
|
|||
|
|
| uploadId | String | 是 | 上传 ID，由初始化分片上传接口返回 | 1234567890abcdef |
|
|||
|
|
| filePath | String | 是 | 文件路径，由初始化分片上传接口返回 | /upload/2026/01/18/1234567890_large-file.zip |
|
|||
|
|
| partNumber | int | 是 | 分片序号，从 1 开始 | 1 |
|
|||
|
|
| chunk | MultipartFile | 是 | 分片数据 | - |
|
|||
|
|
|
|||
|
|
## 响应数据
|
|||
|
|
|
|||
|
|
### 成功响应
|
|||
|
|
|
|||
|
|
**HTTP 状态码**: 200 OK
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "操作成功",
|
|||
|
|
"data": {
|
|||
|
|
"etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
|
|||
|
|
"partNumber": 1
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
| 字段名 | 类型 | 描述 | 示例 |
|
|||
|
|
|--------|------|------|------|
|
|||
|
|
| etag | String | 分片的 ETag 值，用于后续合并文件 | "d41d8cd98f00b204e9800998ecf8427e" |
|
|||
|
|
| partNumber | int | 分片序号 | 1 |
|
|||
|
|
|
|||
|
|
### 失败响应
|
|||
|
|
|
|||
|
|
**HTTP 状态码**: 500 Internal Server Error
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 500,
|
|||
|
|
"message": "分片数据不能为空",
|
|||
|
|
"data": null
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 500,
|
|||
|
|
"message": "上传分片失败：未获取到ETag",
|
|||
|
|
"data": null
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 接口示例
|
|||
|
|
|
|||
|
|
### 请求示例
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -X POST "http://localhost:8080/file/uploadChunk" \
|
|||
|
|
-H "Authorization: Bearer [token]" \
|
|||
|
|
-F "uploadId=1234567890abcdef" \
|
|||
|
|
-F "filePath=/upload/2026/01/18/1234567890_large-file.zip" \
|
|||
|
|
-F "partNumber=1" \
|
|||
|
|
-F "chunk=@/path/to/chunk1.dat"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 响应示例
|
|||
|
|
|
|||
|
|
**成功**:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "操作成功",
|
|||
|
|
"data": {
|
|||
|
|
"etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
|
|||
|
|
"partNumber": 1
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 错误处理
|
|||
|
|
|
|||
|
|
- 分片数据为空时返回错误
|
|||
|
|
- uploadId 或 filePath 为空时返回错误
|
|||
|
|
- partNumber 无效时返回错误
|
|||
|
|
- 上传失败时返回错误
|
|||
|
|
- 未获取到 ETag 时返回错误
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
- 分片序号必须从 1 开始，连续递增
|
|||
|
|
- 每个分片上传成功后会返回 ETag
|
|||
|
|
- ETag 必须妥善保存，用于后续合并文件
|
|||
|
|
- 分片大小建议为 5MB - 100MB
|
|||
|
|
- 需要保存所有分片的 ETag 和 partNumber，用于合并
|
|||
|
|
- 使用系统配置的默认存储桶
|
|||
|
|
|
|||
|
|
## 相关接口
|
|||
|
|
|
|||
|
|
- [初始化分片上传](./0006-init-upload.md) - 初始化分片上传
|
|||
|
|
- [完成分片上传](./0008-complete-upload.md) - 完成分片上传并合并文件
|
|||
|
|
- [统一上传接口](./0002-upload.md) - 普通文件上传（非分片）
|
|||
|
|
|
|||
|
|
## 实现细节
|
|||
|
|
|
|||
|
|
- 使用 `StorageService.uploadPart()` 上传分片
|
|||
|
|
- 返回的 ETag 是分片的唯一标识
|
|||
|
|
- 分片序号必须从 1 开始，连续递增
|
|||
|
|
- 使用系统配置的默认存储桶
|
|||
|
|
- ETag 格式通常为带引号的字符串
|