完成分片上传

1. 接口定位

• 接口名称: 完成分片上传
• 所属域: object
• 业务目标: 在所有分片上传完成后提交分片摘要，触发对象存储合并并生成最终可访问 URL

2. 请求定义

• Method: POST
• Path: /object/complete_multipart_upload
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效令牌
• 幂等性: 非幂等（同一 uploadID 完成后通常不可重复提交）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	登录令牌

Body 参数

字段	必填	类型	说明
uploadID	是	string	分片上传会话 ID（来自 initiate_multipart_upload）
parts	是	array[string]	分片摘要列表（按分片顺序）；当前实现使用每片 MD5 值
name	是	string	目标对象存储路径（含文件名）
contentType	否	string	文件 MIME 类型
cause	否	string	上传来源标记，用于文件分组管理
urlPrefix	否	string	返回 URL 的前缀（scheme+host），不传则使用服务端默认配置

字段约束

• uploadID、parts、name 不能为空。
• name 需通过服务端对象命名规则校验。
• parts 必须与实际已上传分片一一对应且顺序一致，否则可能校验失败。

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	any	业务数据

data 字段结构

字段	类型	说明
url	string	合并完成后的对象访问 URL

5. 业务规则

• 调用方持有合法 token 即可调用，无角色限制。
• 接口会将对象元数据落库（包括 name/hash/size/contentType/cause 等）。
• 成功后返回最终可访问 URL；后续可通过 access_url 再次获取带时效的访问链接。
• 建议调用时机：所有分片 PUT 成功且已收集完整 parts 摘要之后。

6. 错误码与失败场景

错误码	场景	典型报错
1001	参数不合法（uploadID/parts/name 缺失、文件名非法）	ArgsError
500	服务内部错误（分片合并失败、对象存储失败、元数据入库失败）	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/object/complete_multipart_upload", {
  method: "POST",
  headers: {
    operationID: "c2ce4f10-2196-43da-8db2-2e1f8fa24154",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    uploadID: "3a7b5c-upload-session-id",
    parts: ["c4ca4238a0b923820dcc509a6f75849b", "c81e728d9d4c2f636f067f89cc14862c"],
    name: "user/file/20260620/example.mp4",
    contentType: "video/mp4",
    cause: "chat_attachment",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "uploadID": "3a7b5c-upload-session-id",
  "parts": ["c4ca4238a0b923820dcc509a6f75849b", "c81e728d9d4c2f636f067f89cc14862c"],
  "name": "user/file/20260620/example.mp4",
  "contentType": "video/mp4",
  "cause": "chat_attachment"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "url": "https://minio.example.com/openim/user/file/20260620/example.mp4"
  }
}

8. 时序流程

1. 客户端完成全部分片上传，收集分片摘要 parts。
2. 调用 complete_multipart_upload 提交 uploadID + parts + name。
3. 服务端执行分片合并，写入对象元数据并返回最终 url。

9. 变更记录

• 2026-06-20: 首版补充文档发布。