初始化表单直传

1. 接口定位

• 接口名称: 初始化表单直传
• 所属域: object
• 业务目标: 生成对象存储表单直传参数，供客户端通过 HTML Form 或 multipart 表单直接上传文件

2. 请求定义

• Method: POST
• Path: /object/initiate_form_data
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效令牌
• 幂等性: 非幂等（每次调用会生成新的直传会话）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
name	是	string	目标对象名（业务语义名称），如 user/avatar/xxx.jpg
size	是	int64	文件大小（字节）
contentType	否	string	文件 MIME 类型
group	否	string	文件分组标记
millisecond	否	int64	表单直传参数有效期（毫秒）；仅管理员身份可自定义
absolute	否	bool	是否使用 name 作为对象 key；仅管理员身份可生效

字段约束

• name 不能为空且需通过服务端命名规则校验。
• size 必须大于 0。
• 非管理员调用时：millisecond 和 absolute 不生效，服务端固定 10 分钟有效期并使用系统生成 key。

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
id	string	上传会话标识（opaque），complete_form_data 需原样回传
url	string	直传目标 URL
file	string	表单中的文件字段名
header	array[object]	直传请求头参数，每个元素含 key 和 values
formData	object/map	表单字段集合（签名、策略、key 等）
expires	int64	过期时间（毫秒时间戳）
successCodes	array[int32]	期望成功状态码列表

5. 业务规则

• 调用方持有合法 token 即可调用，无角色硬限制。
• 响应中的 id 是服务端签发的上传上下文，客户端不可篡改。
• 表单上传成功后，必须调用 complete_form_data 完成对象校验和元数据入库。

6. 错误码与失败场景

错误码	场景	典型报错
1001	参数不合法（name 为空、size <= 0、文件名非法）	ArgsError
500	服务内部错误（签名生成失败、对象存储异常）	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/object/initiate_form_data", {
  method: "POST",
  headers: {
    operationID: "8fbc4b5e-f8dd-48c4-9c98-d2a709eced01",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "user/file/20260620/example.png",
    size: 204800,
    contentType: "image/png",
    group: "chat_image",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "name": "user/file/20260620/example.png",
  "size": 204800,
  "contentType": "image/png",
  "group": "chat_image"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "id": "eyJuYW1lIjoidXNlci9maWxlLzIwMjYwNjIwL2V4YW1wbGUucG5nIiwic2l6ZSI6MjA0ODAwfQ",
    "url": "https://minio.example.com/openim",
    "file": "file",
    "header": [],
    "formData": {
      "key": "direct/20260620/u_1001/abcd1234.png",
      "policy": "...",
      "x-amz-signature": "..."
    },
    "expires": 1750501200000,
    "successCodes": [200, 201, 204]
  }
}

8. 时序流程

1. 调用 initiate_form_data 获取直传参数（url/header/formData/file）和 id。
2. 客户端按返回参数直传文件到对象存储。
3. 上传完成后调用 complete_form_data，使用 id 完成校验和落库。

9. 变更记录

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