批量获取群成员资料

1. 接口定位

• 接口名称: 批量获取群成员资料
• 所属域: group
• 业务目标: 按群组 ID 与用户 ID 列表，批量返回指定成员在群内的资料

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
groupID	是	string	群组 ID
userIDs	是	array[string]	待查询的用户 ID 列表

字段约束

• groupID 不能为空，否则返回参数错误。
• userIDs 不能为空，否则返回参数错误。

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
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. 业务规则

• 调用方需满足“应用管理员”或“在群内成员”之一。
• 仅返回请求中 userIDs 且在目标群内存在的成员信息。

6. 错误码与失败场景

错误码	场景	典型报错
1001	groupID 为空或 userIDs 为空	ArgsError
1002	非群成员且非管理员	NoPermissionError
500	服务内部错误	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/group/get_group_members_info", {
  method: "POST",
  headers: {
    operationID: "845f7a43-f489-4f00-af69-9cad08ab2b4d",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    groupID: "group_001",
    userIDs: ["u_1001", "u_1002"],
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "groupID": "group_001",
  "userIDs": ["u_1001", "u_1002"]
}

成功响应示例

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

8. 时序流程

1. 校验请求参数（groupID 与 userIDs）。
2. 校验调用者权限（管理员或群内成员）。
3. 查询并组装成员详情返回。

9. 变更记录

• 2026-06-20: 首版补充文档发布。