Kris
2e6f087732
- 完成REQ-010-17（性能优化和限流处理）的所有6个阶段 - 创建ADR文档：0026-performance-optimization.md - 创建Prompt文档：027-performance-optimization.md - 创建会话记录：20260119-performance-optimization.md - 创建变更记录：20260119-performance-optimization.md - 创建复盘报告：20260119-performance-optimization-retro.md - 更新index.md和CHANGELOG.md - 完成REQ-010-2（基础实体类和Mapper创建）的前3个阶段 - 更新ADR文档：0011-entity-mapper-create.md - 创建Prompt文档：002-entity-mapper-create.md - 更新index.md 所有文档均按照SSOT方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
2.8 KiB
2.8 KiB
初始化分片上传
接口信息
- 接口名称: 初始化分片上传
- 接口路径: /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
{
"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
{
"code": 500,
"message": "文件名或文件大小不能为空",
"data": null
}
接口示例
请求示例
curl -X POST "http://localhost:8080/file/initUpload" \
-H "Authorization: Bearer [token]" \
-F "fileName=large-file.zip" \
-F "fileSize=1073741824"
响应示例
成功:
{
"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）
- 初始化成功后需要调用上传分片接口上传各个分片
相关接口
实现细节
- 使用
StorageService.initMultipartUpload()初始化分片上传 - 文件路径包含日期目录：yyyy/MM/dd
- 文件名前缀使用时间戳避免冲突
- 使用系统配置的默认存储桶
- 返回的 uploadId 必须妥善保存，用于后续操作