获取评论列表

1. 接口定位

• 接口名称: 获取评论列表
• 所属域: client/moments
• 业务目标: 获取某条动态的评论列表，支持页码模式和游标模式

2. 请求定义

• Method: POST
• Path: /chatx/moments/comment/list
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，请通过 Header token 传入有效登录令牌
• 幂等性: 幂等（只读接口）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
postID	是	string	动态 ID
pagination	否	object	页码分页对象；仅在页码模式下使用
pagination.pageNumber	否	int32	页码；传 pagination 时需大于等于 1
pagination.showNumber	否	int32	每页条数；传 pagination 时需大于等于 1
cursor	否	string	游标；传入后进入游标模式
limit	否	int32	游标模式条数；必须在 0..50 范围内，0 在游标模式下会按默认值处理

字段说明

• 路由要求 token，但这个接口的 API 层不会把当前用户 userID 注入请求体。
• 当 cursor 非空，或 limit > 0 时，当前实现进入游标模式。
• 当 cursor 为空且 limit 未传或为 0 时，当前实现进入页码模式。
• 页码模式下，如果 pagination 为空，服务端 默认使用 pageNumber=1、showNumber=20。
• 这个接口经过 a2r.Call 调用链，postID、limit、pagination.pageNumber、pagination.showNumber 的校验会在进入服务端处理前执行。

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
total	uint32	评论总数
comments	array<object>	评论列表
nextCursor	string	游标模式下的下一页游标；无更多数据时为空

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，但当前接口不会把 token 中的用户 ID 写进请求。
• 服务端 在查询列表前会先统计该动态的评论总数。
• 游标模式下，评论按 createTime DESC, commentID DESC 返回；当本页条数等于实际查询 limit 时，nextCursor 取最后一条评论的 commentID。
• 页码模式下，评论按 createTime ASC 返回。
• 游标模式中，如果 cursor 对应评论查不到，当前实现不会追加游标过滤，效果等同从最新评论重新开始拉取。
• 返回结果会补齐每条评论的评论人公开资料。

6. 错误码与失败场景

错误码	场景	典型报错
1001	Header 缺少 operationID	header must have operationID
1001	Header 缺少 token	token is empty
1001	postID 为空	postID is empty
1001	limit < 0	limit is invalid
1001	limit > 50	limit exceeds max
1001	pagination.pageNumber < 1	pageNumber is invalid
1001	pagination.showNumber < 1	showNumber is invalid
-	查询评论失败	由数据库层返回
-	查询评论人公开资料失败	由用户资料查询链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10010/chatx/moments/comment/list", {
  method: "POST",
  headers: {
    operationID: "moments-comment-list-001",
    token: "user-token",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    postID: "p_10001",
    cursor: "",
    limit: 20,
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "postID": "p_10001",
  "cursor": "",
  "limit": 20
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 3,
    "comments": [
      {
        "commentID": "c_3003",
        "postID": "p_10001",
        "userID": "u_1002",
        "replyToCommentID": "",
        "content": "收到，安排。",
        "createTime": 1774920500000,
        "commenter": {
          "userID": "u_1002",
          "nickname": "Bob",
          "faceURL": "https://cdn.example.com/avatar/b.png"
        }
      }
    ],
    "nextCursor": "c_3003"
  }
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "limit exceeds max"
}

8. 时序流程

1. 校验 operationID 和 token。
2. API 层解析 JSON 请求，并校验 postID、limit、pagination 的格式约束。
3. 服务端 先统计该动态的评论总数。
4. 按请求进入游标模式或页码模式查询评论。
5. 服务端 批量补齐评论人公开资料。
6. 返回 total、comments 和 nextCursor。

9. 变更记录

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