发布动态

1. 接口定位

• 接口名称: 发布动态
• 所属域: client/moments
• 业务目标: 创建一条新的 moments 动态

2. 请求定义

• Method: POST
• Path: /chatx/moments/post/publish
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，请通过 Header token 传入有效登录令牌
• 幂等性: 非幂等（每次成功都会创建新动态）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
content	否	string	文本内容；与 mediaURLs 至少二选一
mediaURLs	否	array<string>	媒体 URL 列表；与 content 至少二选一
visibility	否	int32	动态可见性；代码注释定义 0=public、1=friends_only、2=private

字段说明

• API 层会在转发前把当前登录用户的 userID 注入请求体，客户端无需传入。
• 当前执行链路会校验 content 与 mediaURLs 不能同时为空。
• 当前执行链路会原样保存传入的 visibility，服务端 中没有再做取值范围拦截。

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
postID	string	新建动态 ID
createTime	int64	创建时间，毫秒时间戳

5. 业务规则

• 路由统一要求 token，API 层会从 token 解析当前用户身份。
• 发布前要求 content 和 mediaURLs 至少有一项非空。
• 服务端使用 UUID 生成 postID。
• 创建时间使用服务端当前时间，并以毫秒时间戳返回。
• 动态写入后不会在本接口内补充点赞数、评论数或作者信息。

6. 错误码与失败场景

错误码	场景	典型报错
1001	Header 缺少 operationID	header must have operationID
1001	Header 缺少 token	token is empty
1001	content 与 mediaURLs 同时为空	content or mediaURLs is required
-	动态写入失败	由数据库层返回

7. 示例

fetch 请求示例

fetch("http://localhost:10010/chatx/moments/post/publish", {
  method: "POST",
  headers: {
    operationID: "moments-publish-001",
    token: "user-token",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: "今天发布一条新动态",
    mediaURLs: ["https://cdn.example.com/moments/cover.jpg"],
    visibility: 1,
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "content": "今天发布一条新动态",
  "mediaURLs": ["https://cdn.example.com/moments/cover.jpg"],
  "visibility": 1
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "postID": "13fc63aa-bb6a-47f8-9b2d-bafac3ef746f",
    "createTime": 1774920200000
  }
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "content or mediaURLs is required"
}

8. 时序流程

1. 校验 operationID 和 token。
2. API 层解析 token，并把当前用户 userID 注入请求。
3. 服务端 校验文本和媒体不能同时为空。
4. 服务端生成 UUID 作为 postID，写入动态记录。
5. 返回 postID 和 createTime。

9. 变更记录

• 2026-03-31: 首版发布，基于 chatx moments API、协议定义和 服务端、数据库实现整理。