[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 相关: Schema Versioning, 事件契约

Protocol Versioning

一句话定义

Protocol Versioning 是管理 SSE 事件协议版本的机制。新增事件类型、修改事件字段时，需要版本化确保新旧客户端兼容。

核心原理

版本化方式

方式	实现	适用场景
Envelope 版本	meta.version: "2"	小版本变更
URL 版本	/api/v2/chat/stream	大版本变更
协商	连接时协商版本	复杂场景

向后兼容

function handleEvent(event: EventEnvelope) {
  const version = event.meta?.version || "1";

  switch (version) {
    case "2":
      return handleV2(event);
    case "1":
    default:
      return handleV1(event);
  }
}

新增事件类型

// 新增事件类型时，旧客户端应该忽略未知类型
function handleEvent(event: EventEnvelope) {
  const handler = handlers[event.event];
  if (handler) {
    handler(event.data);
  } else {
    // 未知事件类型，忽略
    console.debug(`Unknown event type: ${event.event}`);
  }
}

常见坑

1. 不做版本化: 协议变更时旧客户端崩溃
2. 不向后兼容: 新版本发布后旧客户端无法使用
3. 版本太多: 维护成本高

参考资料

• Schema Versioning
• Event Contract