[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 消息: 事件契约, Event Envelope
• 行为: Protocol Versioning
• HTTP: API 版本管理
• 持久化: 数据库迁移与发布兼容性

Schema Versioning

Schema 版本化标识数据结构及其校验规则，帮助生产者、消费者和历史数据读取器选择正确的解释方式。它适用于 API payload、事件和持久化记录，不等于整个通信协议或数据库迁移流程。

兼容性有方向

变化	要检查什么
新增响应可选字段	旧消费者是否允许未知字段
新增必填输入字段	旧生产者是否仍能提交有效数据
新增 enum 值	旧消费者是否认识该值，未知值能否安全处理
改类型、单位或字段含义	结构和语义都可能不兼容
删除字段	是否仍有消费者或历史数据依赖它

“新代码能读旧数据”与“旧代码能读新数据”不是同一个保证。兼容策略必须说明生产者和消费者的方向与支持范围。

版本字段与解析

版本可位于消息 envelope 或外部契约标识中，位置由项目统一约定。不要在一个示例放 version，另一个放 meta.version，却假定二者自动互通。

解析流程应先验证输入格式、版本字段和支持范围，再调用对应解码器。JSON 解析失败、版本类型错误和未知版本不能被忽略或降级成默认 v1。

缺失版本只有在历史契约明确规定时才代表旧版本。静态类型不能替代运行时校验；旧消息回放还应保留足以识别历史 schema 的信息。

迁移与测试

• 优先定义可兼容的扩展窗口，再逐步切换读写。
• 对历史数据使用显式转换；转换后的数据也需校验，不静默编造缺失的业务事实。
• 用新旧格式样例、缺字段、未知 enum、畸形数据和回放用例验证。
• 结构合法不等于行为兼容；顺序、幂等、审批和终态属于 协议版本化 的范围。
• 数据库 DDL 还涉及锁、回填和应用发布顺序，见 database-schema-migration-release-compatibility。