WebSocket 系列—（5）WebSocket 双向聊天系统 API 设计规范

目录

1.概述

2.设计目标与非功能性需求

3.系统架构总览

4.接口清单（REST 与 WebSocket/STOMP）

4.1 REST 接口

4.2 WebSocket/STOMP Endpoint

5.握手与鉴权流程

6.消息协议定义（JSON Schema）

6.1 公共字段

6.2 聊天消息

7.会话、状态与在线管理

8.消息持久化与数据模型

9.可靠性机制

10.心跳、重连与断线处理

11.速率限制与反刷策略

12.安全策略

13.日志、监控与指标

14.扩展与多节点部署

15.示例实现

Node.js WebSocket/STOMP Gateway

客户端发送/重试示例

16.架构与时序图

17.STOMP 操作支持

18.常见错误码与处理建议

19.发布与迁移建议

附录

1.概述

本文档定义了一个面向实时双向聊天（One-to-One 与 Group）的 WebSocket + STOMP API 设计规范，包含握手/鉴权、消息协议、路由、持久化、可靠性、STOMP 支持、扩展与安全等内容，旨在为产品和开发提供可执行的接口规范与实现指导。

2.设计目标与非功能性需求

• 实时性：单条消息端到端延迟 ≤ 200ms。

• 可靠性：消息至少一次投递；支持客户端 ACK、服务端持久化。

• 伸缩性：单服务支持 10K+ 并发连接，水平扩展支撑百万级连接。

• 安全性：强制 TLS（wss://）、握手鉴权（JWT）、消息签名可选。

• 互操作性：兼容 Web、移动与 IoT 设备。

3.系统架构总览

• Client：浏览器/移动/设备，建立 WebSocket/STOMP 连接，发送/接收消息。

• WebSocket Gateway：连接管理、鉴权、路由、心跳、限流。

• Message Service：消息路由、持久化、离线投递、消息状态管理。

• Storage：关系型数据库（MySQL/Postgres）用于会话与索引，NoSQL（Mongo/Dynamo）用于消息存储，Redis 用于在线状态与 Pub/Sub。

• Message Bus：Redis Pub/Sub 或 Kafka，实现多实例消息分发。

4.接口清单（REST 与 WebSocket/STOMP）

4.1 REST 接口

• POST /api/v1/auth/login — 登录，返回 JWT 与用户信息。

• GET /api/v1/users/{userId}/sessions — 列出设备会话。

• GET /api/v1/chats/{chatId}/messages — 拉取历史消息（分页）。

• POST /api/v1/files/upload — 上传文件。

4.2 WebSocket/STOMP Endpoint

• wss://chat.example.com/ws?token=JWT

• 子协议可使用 chat.v1 或 stomp。

• 支持 STOMP 命令：CONNECT, CONNECTED, SEND, SUBSCRIBE, UNSUBSCRIBE, ACK, NACK, DISCONNECT。

5.握手与鉴权流程

1. 客户端通过 REST 登录获取 JWT。

2. 建立 WebSocket/STOMP 连接：wss://chat.example.com/ws?token={JWT}。

3. Gateway 验证 JWT，有效后绑定 userId -> connectionId。

4. 广播上线状态（presence）。

5. 鉴权失败时，返回 401 并关闭连接。

6.消息协议定义（JSON Schema）

6