流媒体与实时通信 / 系统课时

流状态 Webhook 如何保证幂等处理

流状态 Webhook 如何保证幂等处理

直播平台的 Webhook 可能重复投递、延迟到达,甚至出现“断开”晚于“重新推流”的乱序事件。本篇给出一套可直接落地的规则:用 eventId 去重,用 sessionGeneration 区分重连代次,用 stateVersion 决定同一代次内的新旧状态,并让失败重试保持原事件不变。

学习目标

  • 能设计包含 eventId、会话代次和状态版本的流状态回调载荷。
  • 能判断重复、乱序、跨重连事件,避免旧事件覆盖新状态。
  • 能实现失败重试与幂等消费,并用明确的状态转移规则验收。

先把事件身份设计完整

一条 Webhook 至少要有四个能支撑幂等判断的字段:eventId 标识一次通知,streamId 标识直播流,sessionGeneration 标识第几次推流会话,stateVersion 标识该会话内的状态版本。occurredAt 用于审计和排障,但不要单独拿它判断新旧,因为跨机器时钟可能有偏差。

流状态 Webhook 幂等处理与乱序控制流程图

推荐载荷可以固定成下面的结构,生产环境再按需要增加租户、签名和资源版本字段。

json
{
  "eventId": "evt_01HWEBHOOK42",
  "eventType": "stream.started",
  "streamId": "room-1001-main",
  "sessionGeneration": 42,
  "stateVersion": 1,
  "occurredAt": "2026-10-25T10:30:00Z",
  "payload": {
    "publisherId": "publisher-7"
  }
}

预期结果

text
eventId 唯一标识这次投递;同一通知重试时不改变它。
sessionGeneration=42 表示第 42 次推流会话。
stateVersion=1 表示该会话的第一个状态版本。

用代次和版本处理乱序

假设当前数据库中的状态是 generation=41, version=9, state=ended。下一次主播重新推流,服务端必须产生 generation=42, version=1, state=started。此后即使旧会话的 generation=41, version=10 迟到,也只能判为过期,不能把当前状态改回旧会话。

同一代次内只比较 stateVersion。例如先收到 disconnected(version=8),后收到 ended(version=7),后者不能覆盖前者;反过来先收到 ended(version=7),再收到 disconnected(version=8),则可以接受后到事件,但业务状态是否允许从终态回到断开态,应由状态机规则拒绝,而不是靠时间戳猜测。

可以把接受条件固定成:

  1. sessionGeneration 小于当前代次:拒绝更新。
  2. 代次更高:建立新会话状态,并把版本从该事件开始记录。
  3. 代次相同且 stateVersion 小于或等于当前版本:拒绝更新。
  4. 代次和版本都更新:进入状态机校验,通过后写入。

对于 stream.ended 这种终态,建议在同一代次内禁止任何更小或相等版本的状态覆盖;重新开始推流必须使用新的 sessionGeneration。

让重复投递真正幂等

幂等不能只靠“更新数据库时再判断一次”。更稳妥的做法是把 eventId 建唯一键,并在状态更新与事件落库之间使用同一事务或等价的一致性边界。这样同一事件并发到达两次时,最多只有一个消费者完成业务写入,另一个得到“已处理”结果。

下面这个纯 Node.js 示例用内存结构模拟生产环境中的两个存储:processedEvents 相当于幂等表,streams 相当于流状态表。代码不依赖第三方包,可直接用 Node.js 20+ 运行。

js
const processedEvents = new Set();
const streams = new Map();

function consumeWebhook(event) {
  // eventId 是一次通知的稳定身份,重试必须保持不变。
  if (processedEvents.has(event.eventId)) {
    return { action: "duplicate", state: streams.get(event.streamId) ?? null };
  }

  const current = streams.get(event.streamId);

  if (
    current &&
    (event.sessionGeneration < current.sessionGeneration ||
      (event.sessionGeneration === current.sessionGeneration &&
        event.stateVersion <= current.stateVersion))
  ) {
    processedEvents.add(event.eventId);
    return { action: "stale", state: current };
  }

  const next = {
    state: event.eventType,
    sessionGeneration: event.sessionGeneration,
    stateVersion: event.stateVersion
  };

  // 真实数据库中应把事件去重记录和状态更新放在同一事务边界。
  streams.set(event.streamId, next);
  processedEvents.add(event.eventId);

  return { action: "updated", state: next };
}

const first = consumeWebhook({
  eventId: "evt-1",
  eventType: "stream.started",
  streamId: "room-1001-main",
  sessionGeneration: 42,
  stateVersion: 1
});

const retry = consumeWebhook({
  eventId: "evt-1",
  eventType: "stream.started",
  streamId: "room-1001-main",
  sessionGeneration: 42,
  stateVersion: 1
});

const lateOldSession = consumeWebhook({
  eventId: "evt-2",
  eventType: "stream.ended",
  streamId: "room-1001-main",
  sessionGeneration: 41,
  stateVersion: 10
});

console.log(JSON.stringify({ first, retry, lateOldSession }, null, 2));

预期输出

text
{
  "first": {
    "action": "updated",
    "state": {
      "state": "stream.started",
      "sessionGeneration": 42,
      "stateVersion": 1
    }
  },
  "retry": {
    "action": "duplicate",
    "state": {
      "state": "stream.started",
      "sessionGeneration": 42,
      "stateVersion": 1
    }
  },
  "lateOldSession": {
    "action": "stale",
    "state": {
      "state": "stream.started",
      "sessionGeneration": 42,
      "stateVersion": 1
    }
  }
}

这个示例的关键不是 Set 本身,而是判断顺序:先判重复事件,再判代次和版本,最后才执行状态写入。生产环境中可把 processedEvents 换成数据库唯一索引、Redis SET NX 或带唯一约束的事件表,但仍要保证“去重成功”和“业务状态更新”不会长期处于彼此不一致的状态。

重试策略要保证语义不变

Webhook 接收端不应把“已经收到”与“已经处理成功”混为一谈。只有完成幂等校验、状态写入及必要的事件落库后再返回成功;处理异常时返回非 2xx,让发送方按退避策略重试。重试事件必须复用原来的 eventId、sessionGeneration 和 stateVersion,不能每重试一次就生成一个新的事件身份。

一个实用的重试序列可以是 1s、2s、4s、8s、16s,并设置最大重试次数与死信存储。若服务连续失败,死信记录至少保留 eventId、原始载荷、首次失败时间和最后失败原因,方便人工或后台任务重新投递。

验收时检查四种情况

上线前至少构造以下四组测试,每组都要检查最终流状态,而不只看 HTTP 返回码。

测试场景 输入顺序 预期业务结果
正常开始 started g42 v1 状态变为 started
重复通知 started g42 v1、再次收到同一 eventId 只写一次,第二次 duplicate
同代乱序 ended g42 v7、disconnected g42 v6 最终保持 ended 或按业务状态机拒绝非法回退
跨代迟到 started g42 v1、ended g41 v10 最终保持 g42,不被旧会话覆盖

最后特别检查一个容易漏掉的边界:主播快速断开后重新推流时,旧会话的迟到事件必须能够被识别为旧代次;否则“流已恢复”之后又被一条旧的 ended 覆盖,直播间就会出现错误的离线状态。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

流状态 Webhook 如何保证幂等处理

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通