
Hello,我是小兔大白糖。 联调现场:后端说「房间已经建了」,前端列表却进不去——一查,房间还在 pending,成员还没点同意,前端却按「已建会话」去拉消息。写成这篇,给要给自家 IM/聊天后端钉死「房间 + 成员态 + 消息管道 + 已读回执」边界的初中级后端同学。
说明:文中表名、字段、伪代码、索引均为教学脱敏占位写法,不是某家产品的内部实现,也不是「行业标准协议」。读完带走的是可行动的心智模型与设计清单,不是一张必须照抄的 schema。
估计阅读时间:16 分钟
目录
- 为什么现在要关心
- 心智模型:快递柜格口与钥匙
- 精确定义:Room / Membership / Message
- 房间生命周期与一对一去重
- 成员操作矩阵
- 消息管道与已读回执
- 实时层:WS 推送边界
- 存储、索引与分页
- 常见坑
- 小结
为什么现在要关心
聊天后端最贵的不是「能发消息」,而是把房间状态、成员正交标志、已读语义钉成前后端同一套心智。
常见现场:
| 你看到的现象 | 常见真相 |
|---|---|
| 一对一反复「发起聊天」产生多个会话 | 创建时没查是否已有同成员房间;ForceCreate 语义没对前端说清 |
| 列表里会话在,点进去空的 / 报错 | 房间或成员仍是 pending,前端当 active 用 |
| 隐藏了会话又莫名冒出来 | Hide 不等于退群;新消息往往会取消隐藏 |
| 群聊已读把推送打爆 | 把一对一「已读回执」扇出照搬到群 |
| 会话列表越来越慢 | 对每个房间再查成员 / 最后一条消息 → N+1 |
本文只谈:领域模型 → 生命周期 → 成员操作 → 发送/已读管道 → WS 边界 → 索引与分页优先级。 不写空泛的「上微服务 / 上 E2E / 上 Redis 集群」清单。
心智模型:快递柜格口与钥匙
先记住:房间是格口,成员态是钥匙权限;消息是放进格口的包裹。
| 类比 | 对应概念 | 硬规则直觉 |
|---|---|---|
| 格口 | Room | 一对一通常一个格口对应一对人;群组一个格口多人 |
| 钥匙权限 | Membership | pending / active、role、hide / mute / block、exited / kicked 往往是正交标志,别揉成一个 status |
| 包裹 | Message | 正文 + 类型;送达/已读多半按接收者记 |
| 寄件申请单 | ChatRequest(可选) | 陌生人一对一「请求聊天」可与房间 pending 联动 |
类比局限一句说清:快递柜解释「房间存在 ≠ 你能开门取件」;解释不了多端在线、跨实例扇出、推送厂商配额——那些要另开实时层与离线 Push 设计。
精确定义:Room / Membership / Message
四个对象分清楚,后面的 API 才不会互相踩。
Room(房间)
教学字段直觉(不是强制 schema):
| 概念 | 含义 | 硬边界 |
|---|---|---|
room_id | 房间主键 | 对外会话 ID |
room_type | 1 = 一对一,2 = 群组(教学枚举) | 已读回执、退群、去重策略都按类型分叉 |
status | 房间级 pending / active(若你建模) | 有的产品把 pending 只放在成员上——团队只能定一种主真相,别双写打架 |
room_name / 头像等 | 展示元数据 | 一对一常可派生对端资料,不必强依赖房间名 |
Membership(成员相对房间的状态)
关键设计点:很多标志是正交的,不要揉成一个枚举。
| 标志 | 含义 | 注意 |
|---|---|---|
status:pending / active | 是否已正式入房 | pending 时前端不得当「已建立会话」拉全量消息(产品可允许看系统提示) |
role:admin / member | 权限 | Kick / 改群资料等挂这里 |
hide | 会话列表隐藏 | ≠ 退群;新消息常触发取消隐藏 |
mute | 免打扰 | 可带时长或永久 |
block | 屏蔽本会话;可选连带屏蔽对端用户 | 发送侧要拦 |
exited / kicked | 主动退 / 被踢 | 一对一与群语义不同(见下节矩阵) |
把 hide、mute、block、exited 塞进同一个 status 字段,后面几乎一定会出现「静音了却查不到会话」这类互斥 bug。
Message(消息)
| 概念 | 含义 |
|---|---|
正文 + msg_type | 文本 / 媒体 / 系统消息等 |
| 按接收者的送达/已读 | 常见拆到 chat_message_status(教学表名) |
DeleteFor | 删给谁看:仅自己 vs 双方/全员——必须写进产品约定,不能靠前端猜 |
ChatRequest(可选)
陌生人一对一「我想跟你聊」:可与房间/成员 pending 联动;好友或信任关系可通过校验后直接 active,跳过请求流。
房间生命周期与一对一去重
创建房间的硬顺序:校验成员 →(一对一)查重 → 建房插成员 → 可选请求单 → 信任关系可直接激活 → 群可写系统消息。
教学伪代码(脱敏,非真实服务名):
CreateRoom(members, room_type, force_create):
1. 校验 members 合法、未互为非法状态(如全局拉黑策略)
2. if room_type == 一对一:
existing = FindDMRoom(sorted(member_a, member_b))
if existing != nil and not force_create:
return existing // 复用,不要 silently 再建一个
if force_create:
// 产品语义:强制新建;前端必须明示,否则用户看到双会话
3. 插入 chat_room
4. 插入 chat_room_member(status = pending 或 active)
5. 可选:写 chat_request(陌生人)
6. 若已是好友/信任:把相关成员直接置 active
7. 若群组:写系统消息「xxx 创建了群」一对一去重硬规则:
- 默认复用:同一对用户不应因「再点一次发起」产生多个 active DM 房间(除非产品明确要多会话)。
force_create必须是显式契约:名字叫 Force 就说明会打破去重;API 文档与前端文案要对齐,否则联调永远吵「到底该不该新建」。- pending 不是 active:列表可以展示「等待对方同意」,但消息管道、已读、未读角标规则要按 pending 单独定。
成员操作矩阵
先定操作语义,再写 handler;Hide / Mute / Block / Exit 混用是 IM 联调重灾区。
| 操作 | 含义 | 设计注意 |
|---|---|---|
| Invite | 拉人进群 / 发邀请 | 目标成员可进 pending;权限校验 |
| Join | 同意入房 | pending → active;关闭关联 chat_request |
| Reject | 拒绝邀请 | 关闭请求;房间可能解散或保持(产品定) |
| Exit | 主动退 | 群:通常退出成员态;一对一:常是「对我结束会话」而非物理删房——两边产品语义必须分开写 |
| Kick | 管理员踢人 | 校验 role;写 kicked;可选系统消息 |
| Hide | 列表隐藏 | ≠ 退群;新消息可取消隐藏——要写进约定 |
| Mute | 免打扰 | 时长 / 永久;影响 Push,一般不影响落库 |
| Block | 屏蔽 | 可连带屏蔽对端用户;发送与邀请要拦截 |
| Clear | 清历史 | 多为「我这边看不见」;是否物理删另议 |
| Delete | 删会话 | DeleteFor:仅自己 vs 双方——不定死就会出现「我删了你还在」扯皮 |
正交标志提醒:Mute 了仍可能 Hide=false;Exit 了不应还能 Send(除非你做「幽灵只读」——那是另一套产品)。
消息管道与已读回执
发送管道按固定顺序走;已读在一对一与群必须分叉。
发送管道(教学顺序)
SendMessage(room_id, sender, body, msg_type):
1. 校验成员 active、未 block、未 exited/kicked(按你的硬规则)
2. 消息落库(chat_room_message)
3. 可选:媒体预览 / 元数据补全
4. 内容安全 / moderation 钩子(通过才继续扇出;拒绝则标记失败态)
5. 扇出:在线走 WS 事件;离线走 Push
6. 接收方未读 +1(按接收者维度)内容安全钩子放在「已落库、未(或有条件)扇出」的位置,便于审计与事后处置;具体厂商与策略不在本文展开。硬规则是:审核失败不能当普通成功消息推给全员。
已读:一对一 vs 群
| 一对一 | 群 | |
|---|---|---|
| 本地未读 | 清零 / 更新到某 msg_id | 通常同样更新自己的未读 |
| 推已读回执给对端 | 可以;且须尊重「关闭已读回执」用户设置 | 通常不给全员推已读回执 |
| 原因 | 人数固定,回执有产品价值 | 扇出成本高 + 隐私压力大 |
教学伪代码:
ReadMessages(room_id, reader):
更新 reader 在该房间的已读游标 / 消息状态
if room_type == 一对一:
if peer 未关闭已读回执:
推送 read_receipt 事件给 peer(WS;离线是否 Push 由产品定,默认常不 Push)
else: // 群
// 只更新本地/未读;不对全员扇出「谁读了谁」删除消息
DeleteFor = self:只影响自己的可见性 / 状态行。
DeleteFor = both(或 all):双方或全员可见性变更,并考虑是否推 msg_deleted 事件。
没有默认行业标准——你定哪种,就写进 API 合同。
实时层:WS 推送边界
HTTP API 负责写真相;WebSocket 负责在线事件投递;离线走 Push。三者别揉成一个「能推就算成功」。
教学级连接模型:
conn_pool: member_id → connection // 单机直觉生产边界(必须心里有数,本文不展开成 PPT):
- 多端:同一
member_id可能多连接;扇出要定义「推所有端」还是「推活跃端」。 - 多实例:进程内 map 看不见别的实例上的连接 → 需要跨实例 pub/sub 或网关粘滞;没有流量证据前,先把单机正确性做对。
- 订阅粒度:按 room 订阅可降无关流量;心跳保活,断线重连后用游标补消息。
- 投递可观测:至少能区分「已入队 / 已推 WS / 已走 APNs·FCM(或失败原因)」——否则「对方没收到」无法排障。
WS 推送边界硬规则:
- 在线:优先 WS 事件(新消息、已读回执、成员变更等)。
- 离线:走 Push;Mute 应抑制或降级通知。
- 业务成功 ≠ 推送成功:落库成功但推送失败,要有重试或补拉路径(客户端以游标拉取兜底)。
存储、索引与分页
表可按四件套拆;索引跟查询走;列表 N+1 与 offset 分页是最先疼的。
教学表(占位名)
| 表 | 职责 |
|---|---|
chat_room | 房间元数据、类型、可选房间级 status |
chat_room_member | 成员与正交标志 |
chat_room_message | 消息正文与类型 |
chat_message_status | 每接收者送达/已读/删除可见性 |
chat_request | 可选:陌生人请求 |
索引直觉(教学)
| 查询场景 | 索引直觉 |
|---|---|
| 定位某人是否在房 | (room_id, member_id) |
| 某房下接收者状态 / 未读 | (room_id, receiver_mid) |
| 「我的会话列表」 | (member_id, status, exited)(按你过滤条件加减字段) |
优化优先级(有因果,按这个顺序)
- 批量查成员 / 最后一条消息,消灭会话列表 N+1。
- 消息游标分页(
msg_id或单调时间戳),少用大 offset——深翻页在大表上会漂、会慢。 - 房间元数据与在线状态短 TTL 缓存——有读多写少证据再上。
- WS:心跳、按 room 订阅;多实例再加 pub/sub 扇出。
- 再谈服务拆分——没有流量与团队边界证据,不要「为微服务而微服务」。
常见坑
-
pending 当 active
前端进会话、拉历史、亮未读——后端成员还在等同意。合同:列表展示「待确认」,消息 API 对 pending 返回明确错误码或只读系统提示。 -
一对一不去重 / 乱 ForceCreate
用户以为「又发起了一次」,实际多了一个平行宇宙会话。默认复用;强制新建要显式。 -
正交标志揉成单一 status
Hide+Mute+Block+Exit 互斥建模后,免打扰与退群无法共存,SQL 到处OR打补丁。 -
群已读回执扇出
一对一逻辑复制到群,推送与隐私一起炸。群默认只更新自己的已读游标。 -
Hide 语义没写清
用户隐藏后新消息不出现 vs 自动取消隐藏——两种都合理,不写清就必吵。 -
DeleteFor 歧义
「删除」到底是我这边清掉还是双方撤回。API 字段必须暴露,默认值写进文档。 -
列表 N+1 + offset 分页
会话列表每个房间再查最后一条;消息翻页用LIMIT n OFFSET 巨大。先批量、先游标。 -
推送成功当业务成功
WS 失败无补拉,离线 Push 静默丢,用户只觉得「偶发丢消息」。落库与投递分状态追踪。
小结
- Room / Membership / Message 分开建模;hide、mute、block、exited 尽量正交,别揉成一个 status。
- 创建顺序钉死:校验 → 一对一查重(默认复用)→ 插房插人 → 可选 request → 信任可直接 active。
- 发送管道:落库 →(媒体)→ 内容安全钩子 → 扇出 → 未读 +1;审核失败不当成功消息推送。
- 已读分叉:一对一可推回执(尊重关闭设置);群通常只更新本地未读。
- WS 只管在线事件;离线走 Push;多端多实例是边界,先保证单机语义与补拉。
- 优化有因果:先灭 N+1、上游标,再缓存与 WS 扇出,最后才谈拆服务。
教学默认可改:一对一默认复用房间、群不推全员已读、内容安全钩子在「落库后扇出前」——客服多会话、群已读人数、先审后落库等产品变体需另定合同,勿把本文枚举数字写成对外契约。
相关阅读(站内):
- /blog/api_response_envelope/ — 业务失败怎么用信封对齐前后端
- /blog/rate_limit_circuit_breaker/ — 入口闸门与下游保险丝(高扇出场景可对照)