协作编辑工具如何按消息ID去重,避免实时编辑事件被重复应用?

发布人:A5数据发布时间:2026-11-17 15:12阅读量:2

编辑器把一次插入、删除或替换操作发送到服务端后,连接可能在服务端已经写入成功的瞬间断开。客户端没有收到确认,就会在重连时再次发送同一操作。若服务端只根据“收到一条消息”直接修改文档,重复的插入会出现两次,删除范围也可能被错误地执行多次。

因此,按消息 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同时承担三个作用:

  1. 通过主键约束防止同一个文档中的操作 ID被重复登记。
  2. 保存操作摘要,判断重试请求是否与原请求完全一致。
  3. 保存处理后的修订号和操作内容,为断线客户端补发事件提供依据。

文档修改和操作登记必须放在同一个事务中。不能先更新文档,再单独写去重表,否则进程可能在两步之间崩溃,造成文档已经改变但操作记录不存在的状态。

用稳定操作 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则通过可合并的数据结构处理并发修改。它们解决的是并发和顺序问题,不会自动替代业务去重。

正确的处理顺序通常是:

  1. 先用 operationId判断这是不是同一个操作的重试。
  2. 只有新操作才进入版本检查、转换或合并流程。
  3. 转换后的规范化操作写入持久化事件记录。
  4. 文档版本、操作记录和事件记录在同一事务中提交。
  5. 客户端根据事件 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

相关推荐