如何构建一个基于WebSocket的HTML5在线代码审阅实时批注系统？

本文共计859个文字，预计阅读时间需要4分钟。

WebSocket 是实现在线代码审查实时批注系统的核心技术，它使客户端与服务端保持长连接，支持双向、低延迟通信。这使得多人协作时的评论、高亮、光标同步等操作真正实现实时可见。

实时批注与代码行绑定

批注需精确关联到某文件的某一行（甚至某一段字符）。前端解析代码时，可借助 CodeMirror 或 Monaco Editor 的 API 获取当前光标位置、选区范围和行号；后端存储批注时，记录 fileId、lineStart、lineEnd、charStart、charEnd 等字段。WebSocket 消息格式示例如下：

{ "type": "comment:add", "payload": { "fileId": "abc123", "line": 42, "text": "建议改用 const", "userId": "u789", "timestamp": 1715823400 } }

收到消息后，前端在对应行右侧渲染评论气泡，并支持点击展开/收起。

多人光标与选区同步

当多个用户同时查看同一份代码时，可选择性地广播各自光标位置和选区，提升协作感知。关键点包括：

立即学习“前端免费学习笔记（深入）”；

• 仅广播“活跃状态”下的光标（如用户正在输入或拖选时），避免无效流量
• 为每个用户光标添加唯一标识（如 cursorId: userId + timestamp），便于前端区分和清理过期光标
• 使用 editor 的 addContentWidget（Monaco）或 addLineWidget（CodeMirror）动态插入带头像的小型光标标记
• 设置 3 秒无操作自动隐藏，减少界面干扰

冲突处理与操作时序保障

多人同时批注同一行可能引发显示错乱。不依赖锁机制，而是采用轻量级策略：

• 所有 WebSocket 消息携带服务端生成的单调递增 seq 序号，前端按序应用，丢弃乱序旧消息
• 批注提交前，前端校验本地最新 version（由服务端随代码内容下发），若不匹配则先拉取最新代码再重试
• 删除批注采用软删除（标记 isDeleted: true），保留时间戳与操作人，便于审计与恢复

连接可靠性与降级体验

真实网络中 WebSocket 可能断连。应做到：

• 前端自动重连（指数退避：1s → 2s → 4s…），重连后发送 sync:resume 消息，携带最后收到的 seq，服务端补推遗漏事件
• 断连期间本地新增批注暂存于内存（或 localStorage），待恢复后批量提交；若超 5 分钟未恢复，则提示用户导出草稿
• 极端情况下（如 WebSocket 被防火墙拦截），可降级为 Server-Sent Events（SSE）实现单向更新（仅服务端→客户端），保证评论可见性，但放弃光标同步等强实时功能