按序号拉取消息

1. 接口定位

• 接口名称: 按序号拉取消息
• 所属域: msg
• 业务目标: 按会话与序号范围拉取历史消息（支持普通会话与通知会话）

2. 请求定义

• Method: POST
• Path: /msg/pull_msg_by_seq
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效令牌
• 幂等性: 幂等（只读操作）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
userID	是	string	拉取消息的用户 ID
seqRanges	是	array	会话序号范围列表
order	否	int32	拉取顺序，0 升序、1 降序

seqRanges 元素（SeqRange）

字段	必填	类型	说明
conversationID	是	string	会话 ID
begin	是	int64	起始序号
end	是	int64	结束序号
num	否	int64	最大返回条数（普通会话生效）

字段约束

• seqRanges 不能为空。
• begin/end 需满足有效序号区间，服务端会按用户可见范围裁剪。
• order 默认按升序处理（PullOrderAsc=0）。

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
msgs	object	普通会话拉取结果，key 为 conversationID
notificationMsgs	object	通知会话拉取结果，key 为 conversationID

msgs / notificationMsgs value（PullMsgs）

字段	类型	说明
Msgs	array	消息列表（元素为 MsgData）
isEnd	bool	是否到达该方向边界
endSeq	int64	结束序号（部分场景返回）

Msgs 元素（MsgData）关键字段

字段	类型	说明
seq	int64	消息序号
sendID	string	发送者 ID
recvID	string	接收者 ID
groupID	string	群组 ID（群聊时）
contentType	int32	消息类型
content	string	消息内容
sendTime	int64	发送时间（毫秒时间戳）
isRead	bool	是否已读（单聊消息）

5. 业务规则

• 普通会话按 begin/end/num 拉取；通知会话按 begin..end 完整展开序号后拉取。
• isEnd 语义与 order 相关：
  • 升序(0)：到达会话最大可读序号则为 true。
  • 降序(1)：到达会话最小可读序号则为 true。
• 拉取结果按会话分桶返回；若某会话在本次无可见消息，可能不会出现在结果对象中。

6. 错误码与失败场景

错误码	场景	典型报错
1001	参数不合法（如 seqRanges 为空）	ArgsError
1002	无权限访问	NoPermissionError
500	服务内部错误	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/msg/pull_msg_by_seq", {
  method: "POST",
  headers: {
    operationID: "0f4a1a9b-c5da-4e35-9b83-702d472b1fb2",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userID: "u_1001",
    order: 1,
    seqRanges: [
      {
        conversationID: "si_u_1001_u_1002",
        begin: 1000,
        end: 1100,
        num: 50,
      },
    ],
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "userID": "u_1001",
  "order": 1,
  "seqRanges": [
    {
      "conversationID": "si_u_1001_u_1002",
      "begin": 1000,
      "end": 1100,
      "num": 50
    }
  ]
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "msgs": {
      "si_u_1001_u_1002": {
        "Msgs": [
          {
            "seq": 1099,
            "sendID": "u_1002",
            "recvID": "u_1001",
            "contentType": 101,
            "content": "{\"text\":\"hello\"}",
            "sendTime": 1710000000000,
            "isRead": true
          }
        ],
        "isEnd": false,
        "endSeq": 0
      }
    },
    "notificationMsgs": {}
  }
}

8. 时序流程

1. 校验请求并遍历 seqRanges。
2. 按会话类型分别走普通消息或通知消息拉取逻辑。
3. 按 order 计算 isEnd 并组装分桶结果返回。

9. 变更记录

• 2026-07-06: 新增 pull_msg_by_seq 文档。