查询用户所在群列表（adminx）

1. 接口定位

• 接口名称: 查询用户所在群列表
• 所属域: admin/user（adminx）
• 业务目标: 管理员按用户 ID 查询该用户加入的群列表（分页）

2. 请求定义

• Method: POST
• Path: /adminx/user/groups
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效管理员登录令牌
• 幂等性: 幂等（只读查询）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
userID	是	string	目标用户 ID
pagination	是	RequestPagination	分页参数

分页参数结构

字段	必填	类型	说明
pageNumber	是	int32	页码，从 1 开始
showNumber	是	int32	每页条数，大于 0

字段约束

• userID 不能为空（会做首尾空白裁剪）。
• pagination 不能为空，且 pageNumber/showNumber 必须大于 0。

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
total	uint32	群总数
groups	array<GroupInfo>	分页群列表

groups 元素为 openim.sdkws.GroupInfo，常用字段示例：

字段	类型	说明
groupID	string	群 ID
groupName	string	群名称
faceURL	string	群头像
ownerUserID	string	群主 ID
memberCount	uint32	成员数
createTime	int64	创建时间（毫秒）

5. 业务规则

• 仅管理员可调用。
• 服务端通过 open-im-server 的群能力查询目标用户已加入的群，并按分页返回。

6. 错误码与失败场景

错误码	场景	典型报错
1001	userID 为空	userID is empty
1001	pagination 非法	pagination invalid
-	鉴权失败	由管理员鉴权链路返回
-	OpenIM 查询失败	返回下游错误信息

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/user/groups", {
  method: "POST",
  headers: {
    operationID: "adminx-user-groups-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userID: "u1001",
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

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

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 2,
    "groups": [
      {
        "groupID": "g10001",
        "groupName": "运营群",
        "faceURL": "https://example.com/g1.png",
        "ownerUserID": "u9001",
        "memberCount": 56,
        "createTime": 1735718400000
      },
      {
        "groupID": "g10002",
        "groupName": "测试群",
        "faceURL": "https://example.com/g2.png",
        "ownerUserID": "u9002",
        "memberCount": 18,
        "createTime": 1735804800000
      }
    ]
  }
}

8. 时序流程

1. 中间件校验管理员 token。
2. 校验 userID 与 pagination。
3. 获取 OpenIM admin token。
4. 调用 OpenIM 群接口查询目标用户已加入的群列表。
5. 透传 total 与 groups 返回。

9. 变更记录

• 2026-09-01: 首版发布，新增 adminx 用户所在群列表查询接口。