获取群成员列表

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 为空时做普通分页；不为空时做关键字搜索。

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: "alice",
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "groupID": "group_001",
  "keyword": "alice",
  "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: 首版补充文档发布。