分页查询用户

1. 接口定位

• 接口名称: 分页查询用户
• 所属域: user
• 业务目标: 分页检索普通用户列表，支持按用户 ID / 昵称关键字筛选

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
userID	否	string	按用户 ID 关键字筛选
nickName	否	string	按昵称关键字筛选
pagination	是	object	分页参数

pagination 字段

字段	必填	类型	说明
pageNumber	是	int32	页码（从 1 开始）
showNumber	是	int32	每页条数

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
total	int32	命中总数
users	array	用户列表

users 元素（UserInfo）

字段	类型	说明
userID	string	用户 ID
nickname	string	昵称
faceURL	string	头像
ex	string	扩展字段
createTime	int64	创建时间（毫秒时间戳）
appMangerLevel	int32	应用管理等级
globalRecvMsgOpt	int32	全局消息接收设置

5. 业务规则

• 当 userID 与 nickName 均为空时，返回普通用户分页列表。
• 当任一关键字存在时，执行关键字检索后分页。

6. 错误码与失败场景

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

7. 示例

fetch 请求示例

fetch("http://localhost:10002/user/get_users", {
  method: "POST",
  headers: {
    operationID: "6a8bfef5-ec28-4e8f-8aa2-e11dcb53b3cd",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userID: "u_100",
    pagination: {
      pageNumber: 1,
      showNumber: 20
    }
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "userID": "u_100",
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 1,
    "users": [
      {
        "userID": "u_1001",
        "nickname": "Alice",
        "faceURL": "https://example.com/avatar.png",
        "createTime": 1710000000000,
        "globalRecvMsgOpt": 0
      }
    ]
  }
}

8. 时序流程

1. 识别是否需要关键字检索。
2. 读取用户分页数据。
3. 返回用户列表与总数。

9. 变更记录

• 2026-04-09: 首版补充文档发布。