群聊管理 API

认证要求

除特别说明外，所有接口需要 JWT 认证，请求头携带 Authorization: Bearer <token>

创建群聊

POST /api/group/create

请求体

{
  "id": "group_001",
  "name": "技术交流群"
}

字段	类型	必填	限制	说明
id	string	是	-	群 ID（客户端生成）
name	string	是	最长 64 字符	群名称

响应

{ "code": 200, "message": "Group created" }

---

加入群聊

POST /api/group/join

请求体

{ "groupId": "group_001" }

响应

{ "code": 200, "message": "Joined group" }

提示

如果已在群中，返回 "Already in group"。

---

退出群聊

POST /api/group/quit

请求体

{ "groupId": "group_001" }

响应

{ "code": 200, "message": "已退出群聊" }

WebSocket 广播：向剩余群成员推送 group_member_quit 事件。

---

解散群聊

仅群主（creator）可操作。

POST /api/group/dissolve

请求体

{ "groupId": "group_001" }

响应

{ "code": 200, "message": "群已解散" }

WebSocket 广播：向所有群成员推送 group_dissolved 事件。

---

获取群信息

GET /api/group/:groupId

响应示例

{
  "code": 200,
  "data": {
    "id": "group_001",
    "name": "技术交流群",
    "creator_id": "user_a",
    "create_time": 1719820800000,
    "announcement": "欢迎加入！",
    "avatar": "",
    "description": "讨论技术话题",
    "creator_name": "小明",
    "isMember": true,
    "myRole": "creator",
    "memberCount": 25
  }
}

字段	类型	说明
isMember	boolean	当前用户是否为群成员
myRole	string|null	当前用户角色：creator、admin、member 或 null（非成员）
memberCount	number	群成员总数

---

获取群成员列表

GET /api/group/:groupId/members

响应示例

{
  "code": 200,
  "data": [
    {
      "user_id": "user_a",
      "join_time": 1719820800000,
      "role": "creator",
      "is_muted": 0,
      "username": "小明",
      "avatar": "https://example.com/avatar.png",
      "isOnline": 1
    }
  ]
}

---

设置群成员角色

仅群主或管理员可操作。

POST /api/group/member/role

请求体

{
  "groupId": "group_001",
  "targetUserId": "user_b",
  "role": "admin"
}

字段	类型	说明
role	string	目标角色：admin 或 member

响应

{ "code": 200, "message": "角色已更新" }

---

转让群主

仅群主可操作。

POST /api/group/transfer

请求体

{
  "groupId": "group_001",
  "targetUserId": "user_b"
}

响应

{ "code": 200, "message": "群主已转让" }

WebSocket 广播：向所有群成员推送 group_transfer 事件。

---

禁言/解除禁言

仅群主或管理员可操作。

POST /api/group/member/mute

请求体

{
  "groupId": "group_001",
  "targetUserId": "user_b",
  "muted": true
}

字段	类型	说明
muted	boolean	true 禁言，false 解除禁言

响应

{ "code": 200, "message": "已禁言" }

WebSocket 广播：向所有群成员推送 group_member_mute 事件。

---

踢出群成员

仅群主或管理员可操作。

POST /api/group/member/kick

请求体

{
  "groupId": "group_001",
  "targetUserId": "user_b"
}

响应

{ "code": 200, "message": "已踢出成员" }

WebSocket 推送：

• 向被踢用户推送 group_member_kick 事件
• 向剩余群成员推送 group_member_quit 事件

---

更新群公告

仅群主或管理员可操作。

POST /api/group/announcement

请求体

{
  "groupId": "group_001",
  "announcement": "本周六下午 3 点团建"
}

字段	类型	限制	说明
announcement	string	最长 2000 字符	公告内容

响应

{ "code": 200, "message": "群公告已更新" }

WebSocket 广播：向所有群成员推送 group_announcement 事件。

---

更新群信息

仅群主或管理员可操作。

POST /api/group/update

请求体

{
  "groupId": "group_001",
  "name": "新群名称",
  "description": "新的群描述",
  "avatar": "https://example.com/new-avatar.png"
}

字段	类型	必填	限制	说明
groupId	string	是	-	群 ID
name	string	否	最长 64 字符	群名称
description	string	否	最长 500 字符	群描述
avatar	string	否	-	群头像 URL

响应

{ "code": 200, "message": "群信息已更新" }

---

获取所有群列表

GET /api/groups

返回系统中所有群聊（附带创建者名称）。

响应示例

{
  "code": 200,
  "data": [
    {
      "id": "group_001",
      "name": "技术交流群",
      "creator_id": "user_a",
      "creator_name": "小明",
      "create_time": 1719820800000,
      "announcement": "欢迎加入！"
    }
  ]
}

---

获取用户所属群列表

GET /api/users/:userId/groups

响应示例

{
  "code": 200,
  "data": [
    {
      "id": "group_001",
      "name": "技术交流群",
      "creator_id": "user_a",
      "create_time": 1719820800000,
      "announcement": "欢迎加入！",
      "my_role": "member",
      "member_count": 25
    }
  ]
}

字段	类型	说明
my_role	string	当前用户在该群的角色：creator、admin、member
member_count	number	群成员数

---

邀请用户入群

群成员可邀请其他用户加入群聊。

POST /api/group/invite

请求体

{
  "groupId": "group_001",
  "userIds": ["user_c", "user_d"]
}

字段	类型	必填	限制	说明
groupId	string	是	-	群 ID
userIds	string[]	是	最多 50 个	被邀请用户 ID 列表

响应

{ "code": 200, "message": "已邀请 2 人加入群聊" }

WebSocket 推送：向每个被邀请用户推送 group_invite 事件。

{
  "type": "group_invite",
  "data": {
    "groupId": "group_001",
    "groupName": "技术交流群",
    "inviterName": "小明"
  }
}

---

权限说明

操作	群主	管理员	普通成员
编辑群信息	✅	✅	❌
更新群公告	✅	✅	❌
设置成员角色	✅	✅	❌
禁言成员	✅	✅	❌
踢出成员	✅	✅	❌
转让群主	✅	❌	❌
解散群聊	✅	❌	❌
邀请用户	✅	✅	✅
退出群聊	✅	✅	✅