WebSocket中加入seq和幂等校验旨在解决乱序、重复、丢包问题：seq保障消息顺序与缺失检测，idempotency_key确保业务意图唯一性，二者结合实现金融级强一致可靠交付。
在 WebSocket 通信中加入消息序列号（seq）和幂等校验（idempotency key），核心目标是解决网络不稳定导致的重复投递、乱序、丢包问题，尤其适用于金融指令、状态变更、事务型操作等强一致性场景。
一、为什么需要序列号 + 幂等校验
WebSocket 是长连接、全双工协议，但不保证消息顺序、不保证不重复、不提供重传确认机制。客户端或服务端在网络抖动、重连、多实例部署时，可能：
- 同一条业务请求被发了两次（如用户快速双击提交）
- 服务端因超时重发响应，客户端收到两份相同结果
- 客户端重连后重发未确认消息，服务端重复处理
仅靠 WebSocket 的 onmessage 无法区分“新消息”还是“重放消息”。序列号用于识别顺序与缺失，幂等键用于唯一标识一次业务意图，二者结合才能实现端到端的可靠交付。
二、设计消息结构（客户端 & 服务端统一约定）
所有业务消息必须包装为标准信封格式，例如：
{
"seq": 12345, // 全局单调递增序列号（每条发出消息+1）
"idempotency_key": "req_abc789", // 客户端生成的唯一业务ID（如 UUIDv4 或 hash(业务参数)）
"type": "transfer",
"payload": { "from": "A", "to": "B", "amount": 100 },
"timestamp": 1715823456789 // 可选，用于服务端过期判断
}关键规则：
- 客户端每次发送新业务请求，必须生成新
idempotency_key（不可复用），并递增seq -
seq可以是连接级（重连后重置）或会话级（跨连接连续），推荐后者（用 localStorage / IndexedDB 持久化） - 服务端对每个
idempotency_key做去重缓存（如 Redis Set 或内存 LRU Map），缓存时间建议 ≥ 客户端最大重试窗口（如 5–10 分钟） - 服务端返回响应时，必须携带原始请求的
seq和idempotency_key，便于客户端匹配与去重
三、客户端实现要点
客户端需维护状态，并在重连/重发时保持语义一致：
Java Maven Common
下载
Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。
立即学习“Java免费学习笔记（深入）”；
-
序列号管理：用
localStorage存储上一个seq，连接建立后读取并初始化；每次调用send()前自增并保存 -
幂等键生成：对业务操作做确定性哈希（如
sha256(JSON.stringify({type,payload}))），或直接用crypto.randomUUID()（注意兼容性） - 未确认消息缓存：将已发但未收到 ACK 的消息（含 seq + idempotency_key + payload + timestamp）存入内存 Map，定时检查超时（如 30s）后可重发
-
ACK 匹配与去重：收到服务端响应后，用
idempotency_key查找本地待确认队列；若已处理过同 key 响应（比如页面已跳转），直接丢弃 -
重连恢复逻辑：重连成功后，主动向服务端发送
{"type":"sync_seq","last_seq":12345}，服务端可据此补推丢失消息或清空过期缓存
四、服务端校验与响应策略
服务端收到消息后，按以下顺序校验：
- 解析 JSON，校验
seq是否 > 上次该客户端的最大接收 seq（可选，用于检测明显乱序） - 检查
idempotency_key是否已存在于幂等存储中 → 若存在，直接返回上次成功响应（HTTP 200 + 原 payload），不执行业务逻辑 - 若不存在，执行业务逻辑；成功后：
✓ 将idempotency_key写入幂等缓存（带 TTL）
✓ 记录该 key 对应的最终响应体（供后续重放）
✓ 返回响应，包含seq、idempotency_key、业务结果 - 若业务执行失败（如余额不足），仍写入幂等缓存（标记为“失败”），避免下次重试无限循环；返回明确错误码（如
{"status":"failed","reason":"INSUFFICIENT_BALANCE"}） - 建议对高频 key 做布隆过滤预检，降低 Redis 查询压力
不复杂但容易忽略。关键是把「业务意图唯一性」交给 idempotency_key，把「传输过程有序性」交给 seq，两者解耦设计，各自发挥所长。
