协作编辑工具如何按消息ID去重,避免实时编辑事件被重复应用?
编辑器把一次插入、删除或替换操作发送到服务端后,连接可能在服务端已经写入成功的瞬间断开。客户端没有收到确认,就会在重连时再次发送同一操作。若服务端只根据“收到一条消息”直接修改文档,重复的插入会出现两次,删除范围也可能被错误地执行多次。
因此,按消息 ID 去重的核心不是让网络保证消息只到达一次,而是让同一个业务操作被重复投递时,服务端只产生一次状态变更,客户端也只把同一个实时事件应用一次。网络层通常只能做到“至少一次投递”,正确性需要由业务操作 ID、持久化记录和原子事务共同保证。
协作编辑器的去重逻辑最终要落在接口、文档数据库与实时事件服务的运行环境上。A5idc数据可提供香港、美国、日本、新加坡等地区的物理服务器资源,覆盖多核计算、SSD/NVMe存储及不同线路选择,用于承载业务接口和文档数据处理;同时可配合SSL证书与CDN,支持编辑入口的HTTPS连接和静态资源分发,适配不同地区的协作访问场景。
先界定要去重的消息
实时编辑中至少存在两类重复问题:
| 位置 | 重复原因 | 正确处理方式 |
|---|---|---|
| 客户端到服务端 | 发送后连接中断、确认丢失、客户端重试 | 服务端识别相同操作 ID,并返回原处理结果 |
| 服务端到客户端 | 广播重试、客户端重连补发、多个订阅通道重复推送 | 客户端根据事件 ID或文档版本只应用一次 |
| 同一客户端的本地状态 | 乐观更新后又收到自己的服务端回显 | 将回显视为确认,不再对界面重复执行 |
| 多个编辑者之间 | 消息延迟或乱序 | 使用版本号、操作转换或CRDT处理顺序和冲突 |
这里的“消息 ID”应当是业务操作的 ID,而不是每次建立 WebSocket 帧或 HTTP 请求时临时生成的 ID。
例如,用户点击插入按钮时生成一个 operationId:
{
"type": "edit",
"operationId": "01JQ8Z7C4K8H2G4R6D9M3P1A5B",
"docId": "doc-42",
"clientSeq": 37,
"baseRevision": 18,
"action": "insert",
"position": 12,
"text": "新的内容"
}
operationId 需要满足以下条件:
- 在一次编辑操作创建时生成,而不是在每次重试时生成。
- 客户端应先将操作保存到本地待发送队列,再发送到网络。
- 请求超时、连接重连或服务端返回暂时性错误时,继续使用原来的 ID和原来的操作内容。
- 如果用户修改了原操作,应该创建新的操作 ID,而不是复用旧 ID覆盖操作内容。
clientSeq只用于表示同一客户端的本地顺序,不能代替操作 ID。baseRevision用于判断操作建立在哪个文档版本上,也不能作为去重键。
服务端还应计算操作内容摘要。这样可以识别“同一个 ID却携带了不同内容”的异常情况:
同一 docId + operationId + 相同内容摘要
-> 返回之前的处理结果
同一 docId + operationId + 不同内容摘要
-> 拒绝请求并记录异常
客户端传来的 actorId不能直接作为可信身份使用。服务端应当从登录会话、访问令牌或 WebSocket连接上下文中得到操作者身份,再把它写入操作记录。
用稳定操作 ID和原子记录落地
如果只在 Node.js进程里保存一个 Set<string>,重启服务或切换到另一台实例后,去重信息就会消失。多个服务实例之间也无法共享这份状态。
正确性更适合交给持久化数据库。下面的示例使用 PostgreSQL保存文档和已处理操作,运行环境可以采用 Node.js 20及以上、TypeScript 5.x和 pg 8.x。版本号使用 integer只是为了让示例代码更直观;如果单个文档的修订号可能超过 32 位整数范围,应改用 bigint,并在 Node.js侧使用 BigInt,不能直接无条件转换为 Number。
CREATE TABLE documents (
id TEXT PRIMARY KEY,
content TEXT NOT NULL DEFAULT '',
revision INTEGER NOT NULL DEFAULT 0
);
CREATE TABLE applied_operations (
doc_id TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
operation_id TEXT NOT NULL,
actor_id TEXT NOT NULL,
payload_hash CHAR(64) NOT NULL,
operation_payload JSONB NOT NULL,
result_revision INTEGER NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (doc_id, operation_id)
);
CREATE INDEX applied_operations_revision_idx
ON applied_operations (doc_id, result_revision);
applied_operations同时承担三个作用:
- 通过主键约束防止同一个文档中的操作 ID被重复登记。
- 保存操作摘要,判断重试请求是否与原请求完全一致。
- 保存处理后的修订号和操作内容,为断线客户端补发事件提供依据。
文档修改和操作登记必须放在同一个事务中。不能先更新文档,再单独写去重表,否则进程可能在两步之间崩溃,造成文档已经改变但操作记录不存在的状态。

下面是一个简化的服务端实现。示例采用严格版本校验:操作的 baseRevision必须等于当前文档版本。这样可以清楚展示去重逻辑;如果项目采用 OT或CRDT,只需替换版本冲突部分,操作 ID去重仍然保留。
import { createHash } from "node:crypto";
import { Pool } from "pg";
const pool = new Pool({
connectionString: process.env.DATABASE_URL
});
type EditOperation = {
operationId: string;
docId: string;
actorId: string;
clientSeq: number;
baseRevision: number;
action: "insert" | "delete";
position: number;
text?: string;
count?: number;
};
type Ack =
| {
status: "applied" | "duplicate";
operationId: string;
revision: number;
}
| {
status: "base_conflict";
operationId: string;
currentRevision: number;
}
| {
status: "id_conflict";
operationId: string;
};
function canonicalPayload(op: EditOperation): string {
// 生产环境可以使用稳定排序的 JSON 序列化工具。
// 这里通过固定字段顺序保证同一操作得到相同字符串。
return JSON.stringify({
docId: op.docId,
actorId: op.actorId,
clientSeq: op.clientSeq,
baseRevision: op.baseRevision,
action: op.action,
position: op.position,
text: op.text ?? null,
count: op.count ?? null
});
}
function hashOperation(op: EditOperation): string {
return createHash("sha256")
.update(canonicalPayload(op), "utf8")
.digest("hex");
}
function applyText(content: string, op: EditOperation): string {
if (!Number.isInteger(op.position) || op.position < 0) {
throw new Error("INVALID_POSITION");
}
if (op.action === "insert") {
const text = op.text ?? "";
if (op.position > content.length || text.length === 0) {
throw new Error("INVALID_INSERT");
}
return (
content.slice(0, op.position) +
text +
content.slice(op.position)
);
}
const count = op.count ?? 0;
if (
!Number.isInteger(count) ||
count <= 0 ||
op.position + count > content.length
) {
throw new Error("INVALID_DELETE");
}
return (
content.slice(0, op.position) +
content.slice(op.position + count)
);
}
export async function acceptEdit(op: EditOperation): Promise<Ack> {
const client = await pool.connect();
const payloadHash = hashOperation(op);
try {
await client.query("BEGIN");
// 锁住文档行,使同一个文档的版本修改串行化。
const documentResult = await client.query(
`SELECT content, revision
FROM documents
WHERE id = $1
FOR UPDATE`,
[op.docId]
);
if (documentResult.rowCount === 0) {
throw new Error("DOCUMENT_NOT_FOUND");
}
const document = documentResult.rows[0];
const currentRevision = document.revision as number;
// 必须在事务内检查已处理记录。
const existingResult = await client.query(
`SELECT payload_hash, result_revision
FROM applied_operations
WHERE doc_id = $1
AND operation_id = $2`,
[op.docId, op.operationId]
);
if (existingResult.rowCount > 0) {
const existing = existingResult.rows[0];
if (existing.payload_hash !== payloadHash) {
await client.query("ROLLBACK");
return {
status: "id_conflict",
operationId: op.operationId
};
}
await client.query("COMMIT");
return {
status: "duplicate",
operationId: op.operationId,
revision: existing.result_revision as number
};
}
if (op.baseRevision !== currentRevision) {
await client.query("ROLLBACK");
return {
status: "base_conflict",
operationId: op.operationId,
currentRevision
};
}
const newContent = applyText(document.content as string, op);
const newRevision = currentRevision + 1;
await client.query(
`UPDATE documents
SET content = $1,
revision = $2
WHERE id = $3`,
[newContent, newRevision, op.docId]
);
await client.query(
`INSERT INTO applied_operations (
doc_id,
operation_id,
actor_id,
payload_hash,
operation_payload,
result_revision
)
VALUES ($1, $2, $3, $4, $5::jsonb, $6)`,
[
op.docId,
op.operationId,
op.actorId,
payloadHash,
JSON.stringify(op),
newRevision
]
);
await client.query("COMMIT");
return {
status: "applied",
operationId: op.operationId,
revision: newRevision
};
} catch (error) {
await client.query("ROLLBACK").catch(() => {});
throw error;
} finally {
client.release();
}
}
WebSocket或HTTP处理器应在完成权限检查、参数校验后调用这个函数。服务端不能在进入事务前就把操作标记为“已处理”,也不能在事务提交前广播成功事件。
// session.userId 来自服务端会话,不使用客户端自行提交的 actorId。
const operation = parseAndValidateMessage(rawMessage, {
actorId: session.userId
});
const ack = await acceptEdit(operation);
sendToCurrentConnection({
type: "edit_ack",
operationId: operation.operationId,
status: ack.status,
revision: "revision" in ack ? ack.revision : undefined
});
事务提交后,再向其他订阅者广播事件。简单实现可以直接使用 operationId作为事件 ID;如果服务端经过 OT转换后生成了新的规范化操作,则应单独保存稳定的 eventId,并在事件中同时携带 operationId。
{
"type": "document_event",
"eventId": "evt-18",
"operationId": "01JQ8Z7C4K8H2G4R6D9M3P1A5B",
"docId": "doc-42",
"revision": 19,
"action": "insert",
"position": 12,
"text": "新的内容"
}
广播发生在事务提交之后,可以避免客户端收到一个最终回滚的事件。但这仍然存在一个窗口:服务端刚提交事务就发生故障,还没有来得及广播。为此,客户端重连时不能只等待实时推送,还需要根据自己的 revision请求缺失事件。applied_operations中的操作内容和修订号可以用于简单补发;采用 OT或CRDT时,应保存转换后的规范化事件。
让客户端重试与回显不重复
客户端需要保存待确认操作。只使用内存 Map只能覆盖短时间断线,浏览器刷新后仍可能丢失操作。生产项目可以使用 IndexedDB保存待发送和已发送但未确认的操作;下面的 pendingStore表示项目内对 IndexedDB的薄封装,不是浏览器自带的全局对象。
type EditCommand = {
action: "insert" | "delete";
position: number;
text?: string;
count?: number;
};
type PendingOperation = EditOperation & {
state: "queued" | "inflight";
};
interface PendingStore {
put(operation: PendingOperation): Promise<void>;
remove(operationId: string): Promise<void>;
list(docId: string): Promise<PendingOperation[]>;
}
declare const pendingStore: PendingStore;
declare const socket: WebSocket;
const pending = new Map<string, PendingOperation>();
let confirmedRevision = 18;
let nextClientSeq = 37;
async function queueEdit(
docId: string,
actorId: string,
command: EditCommand
): Promise<void> {
const operation: PendingOperation = {
operationId: crypto.randomUUID(),
docId,
actorId,
clientSeq: nextClientSeq++,
baseRevision: confirmedRevision,
...command,
state: "queued"
};
// 必须先持久化,再发送。
await pendingStore.put(operation);
pending.set(operation.operationId, operation);
flushNext(docId);
}
function flushNext(docId: string): void {
if (socket.readyState !== WebSocket.OPEN) {
return;
}
// 严格版本模式下,每个文档先发送一个未确认操作。
// OT/CRDT模式可以允许多个操作并行发送。
const operation = [...pending.values()]
.filter(
item =>
item.docId === docId &&
item.state === "queued"
)
.sort((a, b) => a.clientSeq - b.clientSeq)[0];
if (!operation) {
return;
}
operation.state = "inflight";
void pendingStore.put(operation);
socket.send(
JSON.stringify({
type: "edit",
...operation
})
);
}
async function handleAck(
ack: {
operationId: string;
status: "applied" | "duplicate" | "base_conflict" | "id_conflict";
revision?: number;
currentRevision?: number;
}
): Promise<void> {
const operation = pending.get(ack.operationId);
if (
ack.status === "applied" ||
ack.status === "duplicate"
) {
pending.delete(ack.operationId);
await pendingStore.remove(ack.operationId);
if (ack.revision !== undefined) {
confirmedRevision = Math.max(
confirmedRevision,
ack.revision
);
}
if (operation) {
flushNext(operation.docId);
}
return;
}
if (ack.status === "base_conflict") {
// 不要无限重发原操作。需要获取最新文档,
// 对操作做转换或重新定位后,再创建新的 operationId。
if (operation) {
operation.state = "queued";
await moveToConflictQueue(operation, ack.currentRevision);
}
return;
}
if (ack.status === "id_conflict") {
// 同一个 ID 对应了不同内容,通常表示客户端状态损坏、
// 重复使用 ID或协议实现错误,应停止自动重试。
if (operation) {
await moveToConflictQueue(operation, undefined);
}
}
}
// 项目中实现:把操作移出自动发送队列,等待人工或程序重基。
async function moveToConflictQueue(
operation: PendingOperation,
currentRevision: number | undefined
): Promise<void> {
pending.delete(operation.operationId);
await pendingStore.remove(operation.operationId);
console.warn("edit requires rebase", {
operationId: operation.operationId,
currentRevision
});
}
严格版本模式下,同一文档最好一次只发送一个未确认操作。否则多个本地操作可能都以同一个 baseRevision创建,第一条成功后,后续操作会因为版本过期而被拒绝。
如果界面采用乐观更新,队列中的后续操作还需要根据已经确认的事件重新定位。例如,用户在第 12个字符处插入内容后,另一名用户又在前面插入了 5个字符,原来的位置就不能直接继续使用。这个问题不是 ID去重能够解决的,需要使用操作转换、文本差异算法或CRDT。无论采用哪种协同算法,网络重试时仍然必须复用原 operationId。
服务端回显是另一个容易产生重复显示的地方。如果客户端已经把本地插入操作渲染到界面,随后又收到服务端广播的同一操作,直接再次执行就会出现双重插入。比较稳妥的做法是把界面状态分成两部分:
confirmedDocument:已经按服务端修订号确认的文档。pendingOperations:本地已创建但还没有进入确认版本的操作。
渲染时使用“确认文档加待处理操作”的结果。服务端事件到达后,只把事件应用到确认文档,再从待处理队列中移除自己的对应操作。
type DocumentEvent = {
eventId: string;
operationId: string;
revision: number;
action: "insert" | "delete";
position: number;
text?: string;
count?: number;
};
let confirmedDocument = "";
const bufferedEvents = new Map<number, DocumentEvent>();
const seenEventIds = new Set<string>();
function receiveDocumentEvent(event: DocumentEvent): void {
// 版本已经推进到这里,说明该事件可能是旧连接重发的副本。
if (event.revision <= confirmedRevision) {
return;
}
if (seenEventIds.has(event.eventId)) {
return;
}
// 中间有缺口时不能直接应用当前事件。
if (event.revision !== confirmedRevision + 1) {
bufferedEvents.set(event.revision, event);
requestEventsFrom(confirmedRevision + 1);
return;
}
applyEventInOrder(event);
while (bufferedEvents.has(confirmedRevision + 1)) {
const next = bufferedEvents.get(confirmedRevision + 1)!;
bufferedEvents.delete(confirmedRevision + 1);
applyEventInOrder(next);
}
}
function applyEventInOrder(event: DocumentEvent): void {
confirmedDocument = applyCanonicalEvent(
confirmedDocument,
event
);
confirmedRevision = event.revision;
seenEventIds.add(event.eventId);
// 本地乐观操作只在确认文档中应用一次,
// 这里移除待处理副本,避免再次叠加。
if (pending.has(event.operationId)) {
pending.delete(event.operationId);
void pendingStore.remove(event.operationId);
}
renderDocument(
confirmedDocument,
[...pending.values()]
);
}
declare function requestEventsFrom(revision: number): void;
declare function applyCanonicalEvent(
document: string,
event: DocumentEvent
): string;
declare function renderDocument(
confirmed: string,
pendingOperations: PendingOperation[]
): void;
如果客户端收到的事件版本号大于本地下一版本,不能简单地丢弃。它可能意味着中间事件丢失,也可能是多个连接通道造成了乱序。此时应先放入缓冲区,并向服务端请求从缺失版本开始的事件;如果服务端已经压缩了旧事件,则改为获取该修订号对应的完整快照。
处理顺序、冲突和失败恢复
去重只回答“同一个操作是否已经执行”,不能回答“两个不同操作应该以什么顺序执行”。下面这些异常分支需要分别处理:
| 情况 | 服务端处理 | 客户端动作 |
|---|---|---|
| 相同 ID、相同摘要再次到达 | 不修改文档,返回原修订号 | 删除本地待确认项 |
| 相同 ID、摘要不同 | 拒绝,不覆盖旧记录 | 停止自动重试,记录协议异常 |
| 新 ID但基础版本过期 | 不写入文档,返回当前版本 | 获取快照或事件,转换后创建新操作 |
| 客户端发出请求后连接断开 | 根据重试请求查询已处理记录 | 使用原 ID重发 |
| 事务提交后广播前服务端崩溃 | 从持久化事件记录补发 | 重连后按修订号补齐 |
| 事件版本大于本地下一版本 | 暂存并请求缺失区间 | 补齐后按版本顺序应用 |
| 去重记录被提前删除 | 可能再次执行旧操作 | 只有在快照边界明确后才能清理 |
其中,客户端重试时最常见的错误是重新生成 ID:
第一次发送:operationId = op-1001,服务端已提交,确认丢失
错误重试: operationId = op-1002
服务端会把 op-1002看成一条全新的编辑,自然无法判断它其实是 op-1001的重试。正确方式是:
第一次发送:operationId = op-1001
重新连接: operationId = op-1001
再次超时: operationId = op-1001
严格版本校验与协同算法的差异
示例中的 baseRevision不匹配就返回冲突,适合以下场景:
- 文档编辑频率不高。
- 操作失败后可以提示用户重新加载。
- 业务更重视不误写,而不是无感合并。
- 操作本身不容易自动转换。
多人实时协作通常需要更复杂的处理。OT会根据已经确认的远端操作调整本地操作的位置;CRDT则通过可合并的数据结构处理并发修改。它们解决的是并发和顺序问题,不会自动替代业务去重。
正确的处理顺序通常是:
- 先用
operationId判断这是不是同一个操作的重试。 - 只有新操作才进入版本检查、转换或合并流程。
- 转换后的规范化操作写入持久化事件记录。
- 文档版本、操作记录和事件记录在同一事务中提交。
- 客户端根据事件 ID和修订号应用规范化结果。
如果先进行 OT转换,再去重,同一个原始操作重复进入转换流程,可能因为当前文档状态已经变化而得到不同位置,最终仍会产生重复修改。
去重记录不能随意设置短 TTL
Redis中的以下写法可以作为快速过滤:
SET dedupe:doc-42:op-1001 1 NX EX 86400
但它不适合作为唯一正确性依据。一天后相同操作再次到达,键已经过期,操作可能被重新执行。服务重启、网络延迟超过 TTL和广播失败也会产生类似问题。
Redis可以用于降低重复请求对数据库的压力,数据库唯一约束仍应作为最终依据。若必须清理旧操作记录,应先建立快照边界:
- 文档已经生成某个修订号的完整快照。
- 所有允许重试的客户端都不会再使用快照以前的操作。
- 低于快照修订号的客户端必须重新下载快照,而不是继续提交旧操作。
- 清理后的旧操作 ID不能被新的文档实例复用。
如果文档删除后允许使用同一个 docId创建新文档,最好增加文档代次或使用不可复用的文档 ID,避免新文档继承旧文档的去重语义。
验证结果并选择实现边界
接入完成后,可以用同一个文档和固定的操作 ID执行以下验证。下面的结果是期望结果示例,不代表某次实际运行日志。
验证重复请求
第一次发送:
{
"type": "edit_ack",
"operationId": "op-1001",
"status": "applied",
"revision": 19
}
不改变请求内容,再发送一次:
{
"type": "edit_ack",
"operationId": "op-1001",
"status": "duplicate",
"revision": 19
}
此时文档版本应当只从 18变为 19,内容中的插入文本也只能出现一次。可以使用只读查询确认:

SELECT id, revision, content
FROM documents
WHERE id = 'doc-42';
SELECT operation_id, result_revision
FROM applied_operations
WHERE doc_id = 'doc-42'
AND operation_id = 'op-1001';
验证确认丢失后的重试
测试时可以在服务端提交事务后、发送确认前主动关闭连接,或者在客户端发送后立即断开网络。客户端重连后重发同一操作,应该得到 duplicate,而不是新的 applied。
需要同时检查:
- 文档修订号是否只增加一次。
- 操作表中是否只有一条主键记录。
- 服务端是否没有向其他客户端广播两次。
- 当前客户端收到自己的回显时,界面是否没有重复插入。
- 其他客户端断线重连后,按修订号补齐事件仍只应用一次。
验证篡改 ID内容
先成功提交 op-1001,再把同一个 ID的文本改成另一段内容重新发送。服务端应返回 id_conflict,文档内容和修订号都不能改变。这项测试可以发现客户端是否在重试时错误复用了 ID,以及服务端是否只检查 ID而没有校验操作摘要。
几种实现方式的取舍
| 方案 | 能解决的问题 | 主要边界 |
|---|---|---|
进程内 Set | 同一进程短时间内的重复请求 | 重启、扩容和故障切换后失效 |
Redis SET NX | 快速过滤重复请求 | TTL、崩溃窗口和数据库写入不原子 |
| 数据库唯一键加事务 | 持久化保证状态变更只执行一次 | 高并发文档需要控制锁竞争 |
| 事件日志加修订号 | 支持断线补发、顺序恢复和审计 | 需要设计保留、压缩和快照策略 |
| OT或CRDT | 处理并发修改和操作转换 | 不替代操作 ID去重,模型复杂度更高 |
对于普通的实时表单、低频编辑器或管理后台,可以先使用数据库唯一键、事务和严格版本校验。对于多人同时编辑同一篇长文档,则应在这套去重基础上增加事件日志、断线补发以及 OT或CRDT,而不是仅仅提高 WebSocket发送速度。
最终应把去重逻辑放在“业务操作真正修改文档”的入口处:客户端生成并持久化稳定 ID,服务端在事务中检查操作记录、修改文档并登记结果,提交后再广播事件;客户端收到确认或回显时按照 ID和修订号更新状态。这样即使发生重连、确认丢失、服务端重启或事件重复推送,重复到达的消息也只会重复确认,不会重复改变文档内容。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/10008.html
