# 上传文件分片

## 接口信息

- **接口名称**: 上传文件分片
- **接口路径**: /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 格式通常为带引号的字符串