查询群组（分页/条件）

1. 接口定位

• 接口名称: 查询群组（分页/条件）
• 所属域: group
• 业务目标: 按群 ID 精确查询或按群名模糊检索群组列表，供后台管理与运营检索使用

2. 请求定义

• Method: POST
• Path: /group/get_groups
• Content-Type: 推荐 application/json（服务端按 JSON body 解析，当前未对该请求头做强校验）
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效令牌
• 幂等性: 幂等（只读操作）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
groupID	否	string	群组 ID，传入后优先按 ID 精确查询
groupName	否	string	群组名称关键字（按名称检索时生效）
pagination	否	object	分页参数，按名称检索时建议传入

pagination 字段

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

字段约束

• groupID 非空时，服务端按群 ID 查询，groupName/pagination 可忽略。
• groupID 为空时，按 groupName + pagination 做检索。

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
total	uint32	命中总数
groups	array	群组列表

groups 元素（CMSGroup）

字段	类型	说明
groupInfo	object	群基础信息（含 groupID/groupName/notification/introduction/faceURL/createTime/status/groupType/needVerification/lookMemberInfo/appMangerLevel/memberCount 等）
groupOwnerUserName	string	群主昵称
groupOwnerUserID	string	群主用户 ID

5. 业务规则

• 当 groupID 存在且命中时，返回单群结果（total 为命中数量）。
• 当按关键字检索时，结果受分页参数控制。

6. 错误码与失败场景

错误码	场景	典型报错
1001	请求参数不合法	ArgsError
1002	无权限访问	NoPermissionError
500	服务内部错误	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/group/get_groups", {
  method: "POST",
  headers: {
    operationID: "e5d9f31f-42c8-49b3-9f8f-8ce4f8e12a11",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    groupName: "openim",
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "groupName": "openim",
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 1,
    "groups": [
      {
        "groupInfo": {
          "groupID": "group_001",
          "groupName": "OpenIM 技术交流群",
          "ownerUserID": "u_admin",
          "memberCount": 86,
          "status": 0
        },
        "groupOwnerUserName": "管理员",
        "groupOwnerUserID": "u_admin"
      }
    ]
  }
}

8. 时序流程

1. 解析请求参数并判断是否为 groupID 精确查询。
2. 查询群组数据及群主信息、成员数量。
3. 组装 CMS 视图返回。

9. 变更记录

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