Skip to content

发布动态 ​

1. 接口定位 ​

  • 接口名称: 发布动态
  • 所属域: chat/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. 响应结构 ​

通用响应包裹 ​

字段类型说明
errCodeint错误码,0 表示成功
errMsgstring错误简述
errDltstring错误详情
dataobject业务数据

data 字段 ​

字段类型说明
postIDstring新建动态 ID
createTimeint64创建时间,毫秒时间戳

5. 业务规则 ​

  • 路由统一要求 token,API 层会从 token 解析当前用户身份。
  • 发布前要求 content 和 mediaURLs 至少有一项非空。
  • 服务端使用 UUID 生成 postID。
  • 创建时间使用服务端当前时间,并以毫秒时间戳返回。
  • 审核策略:
    • 发布者在“动态可信发布者”名单中: 发帖直接标记为已审核通过。
    • 发布者不在“动态可信发布者”名单中: 发帖标记为待审核。
    • 当可信发布者名单查询异常时,服务端会降级为待审核(fail-closed)。
  • 动态写入后不会在本接口内补充点赞数、评论数或作者信息。

6. 错误码与失败场景 ​

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

7. 示例 ​

fetch 请求示例 ​

javascript
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) ​

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

成功响应示例 ​

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

失败响应示例 ​

json
{
  "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、协议定义和 服务端、数据库实现整理。
  • 2026-06-01: 新增动态可信发布者免审策略;可信发布者发布动态直通审核通过,名单查询异常时降级待审核。