English
devexamples
← 中文资源

简体中文版本

在合并前校验 Schema 兼容性

在 CI 中调用 Schema Registry 兼容性检查，阻止不向后兼容的 Avro 变更进入生产并影响消费者。

阅读英文原文

概述

Schema Registry 保存版本并执行兼容性模式。BACKWARD 表示新 Schema 能读取上一版本写入的数据，适合消费者滞后于生产者的滚动升级；FULL 还要求旧 Schema 能读取新数据。把兼容性设为 NONE 等于放弃 Registry 的保护。

步骤

  1. 将 subject 的兼容性设为 BACKWARD：
curl -s -X PUT -H "Content-Type: application/json" \
  --data '{"compatibility":"BACKWARD"}' \
  http://schema-registry.internal:8081/config/orders-value
  1. 在 CI 中对候选 Schema 做试运行检查，不创建新版本：
curl -s -X POST \
  -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data @schemas/orders-value.json \
  http://schema-registry.internal:8081/compatibility/subjects/orders-value/versions/latest
  1. 解析返回 JSON，只有包含 "is_compatible":true 才继续，网络错误或 subject 不存在都应让构建失败，而不是当作通过。
  2. 检查通过后再提交注册并发布消费者契约测试。

验证

预期新增带默认值的可选字段返回 {"is_compatible":true}；删除无默认值的必填字段返回 false 并使 CI 失败。注册成功后记录新的 version id，旧版本仍可查询以便重放历史数据。

注意事项

  • 结构兼容不代表语义兼容，单位变化、枚举含义改变仍需契约测试。
  • 网络异常时必须 fail closed，避免 Registry 不可达时静默放行。
  • 删除字段只有在消费者能处理缺失值时才安全，需要消费者侧验证。
  • 事件头中应携带 Schema 版本，消费者可显式拒绝不支持的版本。