datai/datai-scenes/datai-scene-salesforce/docs/api-docs/file/FileController/0007-upload-chunk.md

上传文件分片

接口信息

• 接口名称: 上传文件分片
• 接口路径: /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

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
    "partNumber": 1
  }
}

字段名	类型	描述	示例
etag	String	分片的 ETag 值，用于后续合并文件	"d41d8cd98f00b204e9800998ecf8427e"
partNumber	int	分片序号	1

失败响应

HTTP 状态码: 500 Internal Server Error

{
  "code": 500,
  "message": "分片数据不能为空",
  "data": null
}

{
  "code": 500,
  "message": "上传分片失败：未获取到ETag",
  "data": null
}

接口示例

请求示例

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"

响应示例

成功:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
    "partNumber": 1
  }
}

错误处理

• 分片数据为空时返回错误
• uploadId 或 filePath 为空时返回错误
• partNumber 无效时返回错误
• 上传失败时返回错误
• 未获取到 ETag 时返回错误

注意事项

• 分片序号必须从 1 开始，连续递增
• 每个分片上传成功后会返回 ETag
• ETag 必须妥善保存，用于后续合并文件
• 分片大小建议为 5MB - 100MB
• 需要保存所有分片的 ETag 和 partNumber，用于合并
• 使用系统配置的默认存储桶

相关接口

• 初始化分片上传 - 初始化分片上传
• 完成分片上传 - 完成分片上传并合并文件
• 统一上传接口 - 普通文件上传（非分片）

实现细节

• 使用 StorageService.uploadPart() 上传分片
• 返回的 ETag 是分片的唯一标识
• 分片序号必须从 1 开始，连续递增
• 使用系统配置的默认存储桶
• ETag 格式通常为带引号的字符串