获取群内官方成员用户 ID 列表(chatx)
1. 接口定位
- 接口名称: 获取群内官方成员用户 ID 列表(chatx)
- 所属域: chat/group(chatx)
- 业务目标: 传入群 ID,返回该群成员中官方标识(本地
attribute.is_official=true)的用户 ID 列表
2. 请求定义
- Method:
POST - Path:
/chatx/group/official_member_user_ids - Content-Type: 推荐
application/json - operationID: 必填,请通过 Header
operationID传入 - 鉴权: 必填,需要通过 Header
token传入有效登录令牌 - 幂等性: 幂等(只读操作)
3. 请求参数
Header 参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| operationID | 是 | string | 链路追踪 ID |
| token | 是 | string | 登录令牌 |
Body 参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| groupID | 是 | string | 群 ID |
字段约束
groupID必填,不能为空。
4. 响应结构
通用响应包裹
| 字段 | 类型 | 说明 |
|---|---|---|
| errCode | int | 错误码,0 表示成功 |
| errMsg | string | 错误简述 |
| errDlt | string | 错误详情 |
| data | object | 业务数据 |
data 字段结构
| 字段 | 类型 | 说明 |
|---|---|---|
| userIDs | []string | 群内官方成员用户 ID 列表 |
5. 权限与业务规则
- 管理员可查询任意群。
- 普通用户仅可查询自己所在群。
- 官方标识来源于本地 chat 用户属性表
attribute.is_official。 - 返回顺序按群成员顺序输出,便于前端直接标记。
6. 性能说明
- 先调用 OpenIM 获取群成员 userID 列表。
- 再按
user_id in (...)+is_official=true做一次本地过滤查询。 - 本地查询仅投影
user_id字段,避免回表传输整行用户资料。
7. 错误码与失败场景
| 错误码 | 场景 | 典型报错 |
|---|---|---|
| 1001 | 参数错误 | groupID is empty |
| 1002 | token 无效/缺失 | NoPermission |
| 1002 | 普通用户非群成员 | NoPermission(op user not in group) |
| 5000+ | 上游 OpenIM 调用失败 | 透传上游错误码与错误信息 |
8. 示例
请求示例
json
{
"groupID": "group_001"
}成功响应示例
json
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"userIDs": ["u_1001", "u_1009", "u_2003"]
}
}9. 时序流程
- 中间件校验 token。
- RPC 层校验调用者身份(管理员或普通用户)。
- 普通用户先校验是否在目标群内。
- 拉取群成员 userID 列表。
- 本地 attribute 表过滤
is_official=true。 - 返回官方成员 userID 列表。
10. 变更记录
- 2026-09-29: 首版发布,新增群内官方成员用户 ID 列表查询能力。