[!info] related notes

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

Schema Versioning

一句话定义

Schema Versioning 是管理 API 和事件协议版本演进的工程实践。当事件格式、API 参数或数据结构需要变更时，通过版本化确保新旧客户端能共存。

它解决什么问题

AI Agent 应用的协议经常演进：

• 新增事件类型（如 heartbeat）
• 修改事件字段（如 token_usage 格式变更）
• 废弃旧字段

如果没有版本管理，前端旧版本和后端新版本可能不兼容。

核心原理

版本化策略

策略	方式	适用场景
URL 版本	/api/v1/chat, /api/v2/chat	大版本变更
Header 版本	X-API-Version: 2	小版本变更
事件版本	event 中带 version 字段	事件协议演进
向后兼容	新字段可选，旧字段保留	渐进式变更

事件版本化

{
  "event": "tool_call_result",
  "version": "2",
  "data": {
    "tool_call_id": "xxx",
    "result": { ... },
    "duration_ms": 230
  }
}

Go 实现

func parseEvent(data []byte) (Event, error) {
    var base struct {
        Event   string `json:"event"`
        Version string `json:"version"`
    }
    json.Unmarshal(data, &base)

    switch base.Version {
    case "2":
        return parseEventV2(data)
    case "1", "":
        return parseEventV1(data)
    default:
        return nil, fmt.Errorf("unknown version: %s", base.Version)
    }
}

常见坑

1. 不做版本化: 协议变更时前后端不兼容
2. 不向后兼容: 新版本发布后旧客户端崩溃
3. 不做废弃通知: 旧版本悄悄被移除
4. 版本太多: 维护成本高

参考资料

• Event Contract
• API Versioning Best Practices