添加评论

1. 接口定位

• 接口名称: 添加评论
• 所属域: client/moments
• 业务目标: 给指定动态新增一条评论，或回复一条已有评论

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
postID	是	string	动态 ID
replyToCommentID	否	string	被回复的评论 ID；为空表示顶级评论
content	是	string	评论内容

字段说明

• API 层会在转发前把当前登录用户的 userID 注入请求体，客户端无需传入。
• 当前实现会先校验动态存在。
• 当前实现会原样保存 replyToCommentID，在本链路里没有看到对该评论是否存在、是否属于同一动态的额外校验。

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
comment	object	新建评论详情

comment 对象

字段	类型	说明
commentID	string	评论 ID
postID	string	所属动态 ID
userID	string	评论人用户 ID
replyToCommentID	string	回复目标评论 ID；顶级评论为空
content	string	评论内容
createTime	int64	创建时间，毫秒时间戳
commenter	object	评论人公开资料

commenter 对象

字段	类型	说明
userID	string	用户 ID
nickname	string	昵称
faceURL	string	头像 URL

5. 业务规则

• 路由统一要求 token。
• API 层从 token 中解析当前用户，并把该用户作为评论作者。
• 服务端 要求 postID、userID、content 都存在。
• 服务端使用 UUID 生成 commentID。
• 返回结果会补齐评论人公开资料。

6. 错误码与失败场景

错误码	场景	典型报错
1001	Header 缺少 operationID	header must have operationID
1001	Header 缺少 token	token is empty
1001	postID 为空	postID and userID are required
1001	content 为空	content is required
-	动态不存在	由动态查询链路返回
-	评论写入失败	由数据库层返回

7. 示例

fetch 请求示例

fetch("http://localhost:10010/chatx/moments/comment/add", {
  method: "POST",
  headers: {
    operationID: "moments-comment-add-001",
    token: "user-token",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    postID: "p_10001",
    replyToCommentID: "",
    content: "收到，安排。",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "postID": "p_10001",
  "replyToCommentID": "",
  "content": "收到，安排。"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "comment": {
      "commentID": "ad01e8d7-4d0b-44c1-b4c2-1c4e53280511",
      "postID": "p_10001",
      "userID": "u_1002",
      "replyToCommentID": "",
      "content": "收到，安排。",
      "createTime": 1774920400000,
      "commenter": {
        "userID": "u_1002",
        "nickname": "Bob",
        "faceURL": "https://cdn.example.com/avatar/b.png"
      }
    }
  }
}

失败响应示例

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

8. 时序流程

1. 校验 operationID 和 token。
2. API 层解析 token，并把当前用户 userID 注入请求。
3. 服务端 校验 postID、userID 和 content。
4. 服务端 确认目标动态存在。
5. 服务端生成 commentID 并写入评论。
6. 读取评论人公开资料并返回完整评论对象。

9. 变更记录

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