获取群成员列表

1. 接口定位

• 接口名称: 获取群成员列表
• 所属域: group
• 业务目标: 按群 ID 拉取群成员分页列表，支持关键字筛选

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
groupID	是	string	群组 ID
keyword	否	string	关键字（当前实现并不支持按用户 ID 搜索；见下文“业务规则”与“已知限制”）
filter	否	int32	兼容保留字段；当前服务端实现未使用该值参与过滤
pagination	否	object	分页参数

pagination 字段

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

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
total	uint32	成员总数
members	array	成员信息列表

members 元素（GroupMemberFullInfo）

字段	类型	说明
groupID	string	群组 ID
userID	string	用户 ID
roleLevel	int32	角色级别（普通成员/管理员/群主）
joinTime	int64	入群时间（毫秒时间戳）
nickname	string	群昵称
faceURL	string	头像
muteEndTime	int64	禁言截止时间（毫秒时间戳）
inviterUserID	string	邀请人 ID
ex	string	扩展字段

5. 业务规则

• 调用方需满足“应用管理员”或“在群内成员”之一。
• keyword 为空时做普通分页。
• keyword 不为空时，服务端会走搜索分支，但当前版本存在参数传递问题，可能导致搜索结果为空。
• 当前实现未按 userID 做匹配（即不支持通过成员 ID 关键字检索）。
• filter 当前不影响查询结果，传空或传值行为一致。

5.1 已知限制（当前版本）

• keyword 搜索在当前实现中与预期不一致：常见情况下会返回空列表。
• 使用成员昵称或成员 ID 进行 keyword 搜索，均可能无法命中。
• 若业务侧需要稳定检索，建议临时使用 keyword 为空的分页查询，并在客户端侧做过滤。

6. 错误码与失败场景

错误码	场景	典型报错
1002	非群成员且非管理员	NoPermissionError
1201	群组不存在	GroupIDNotFoundError
500	服务内部错误	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/group/get_group_member_list", {
  method: "POST",
  headers: {
    operationID: "6aa95b90-59af-4954-8a20-a01d9b65e8fc",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    groupID: "group_001",
    keyword: "", // 建议当前版本留空，走稳定分页路径
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "groupID": "group_001",
  "keyword": "",
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 2,
    "members": [
      {
        "groupID": "group_001",
        "userID": "u_1001",
        "roleLevel": 2,
        "nickname": "alice",
        "joinTime": 1710000000000,
        "muteEndTime": 0
      }
    ]
  }
}

8. 时序流程

1. 校验调用者权限（管理员或群内成员）。
2. 按 keyword 分支执行分页查询或搜索。
3. 组装群成员详情并返回。

9. 变更记录

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