avro 枚举类型在 schema 演进中不支持“新增符号 + 默认值”的前向兼容读取，根本原因在于 json 解析器严格校验符号合法性，而非依赖默认值兜底；真正的兼容需结合二进制格式、schema 注册中心策略及枚举设计规范。
avro 枚举类型在 schema 演进中不支持“新增符号 + 默认值”的前向兼容读取，根本原因在于 json 解析器严格校验符号合法性，而非依赖默认值兜底；真正的兼容需结合二进制格式、schema 注册中心策略及枚举设计规范。
Avro 的枚举兼容性常被误解——尤其当开发者看到文档中“default 用于未知符号”这一描述时，容易误以为只要为 enum 指定了默认值（如 "UNKNOWN"），就能安全读取含新符号（如 "BLACK"）的旧 schema 消息。但事实并非如此：该默认值仅在 缺失字段 或 字段值为空 时生效，而非用于“符号不在 symbols 列表中”的场景。
关键在于 Avro 的解析机制分层：
- 二进制格式（Binary encoding）：读取时若遇到未知 enum 符号，ResolvingDecoder 会跳过该字段并使用默认值（符合 Avro 规范），因此 v2.avro（二进制）可被 v1.avsc 成功读取，输出 {"color": "unknown"}；
- JSON 格式（JSON encoding）：JsonDecoder 在 readEnum() 阶段直接校验 symbol 是否存在于 reader schema 的 symbols 数组中，一旦发现 "BLACK" 不在 ["BLUE","YELLOW","GREEN","UNKNOWN"] 中，立即抛出 AvroTypeException，根本不触发默认值逻辑。
这解释了你遇到的异常：jsonDecoder 无法容忍未知 symbol，而 default 对 JSON 解析无效。
✅ 正确实现全兼容（Full Compatibility）的实践建议：
优先使用二进制编码
生产环境应避免 JSON 序列化 Avro 数据。二进制格式天然支持 enum 新增符号的前向兼容（reader 忽略未知 symbol，回退至 default）。-
遵循“仅追加、不重排、保留 UNKNOWN”原则
{ "type": "enum", "name": "ColorType", "symbols": ["UNKNOWN", "BLUE", "YELLOW", "GREEN"], "default": "UNKNOWN" }- "UNKNOWN" 必须作为首个 symbol（确保其 ordinal=0，便于兼容性处理）；
- 新增 symbol（如 "BLACK"）只能追加到末尾，不可插入或重排序；
- 字段级 default 也需显式声明（如 "default": "UNKNOWN"）。
-
启用 Schema Registry 的兼容性检查
Confluent Schema Registry 的 FULL 兼容性模式会静态校验：- writer schema 的 enum symbols 是 reader schema symbols 的超集（允许新增）；
- 但仅对二进制数据有效，且要求双方 schema 均注册并启用验证。
-
避免 JSON 作为跨版本传输格式
若必须用 JSON（如调试或 API 响应），应在应用层做适配：// 示例：预处理 JSON，将未知 enum 值映射为 UNKNOWN String safeJson = originalJson.replace("\"BLACK\"", "\"UNKNOWN\"");
⚠️ 注意事项：
- Avro 1.11+ 仍不改变 JSON 解析器的行为，此限制属设计使然，非 bug；
- SpecificDatumReader 和 GenericDatumReader 在 JSON 场景下表现一致；
- 使用 avro-tools tojson --reader-schema-file 测试时，务必传入 .avro（二进制）文件，而非 .json——后者会复现你的错误。
总结：Avro 的 enum 兼容性是格式敏感的。默认值不是万能兜底，而是 schema 演进的协作契约。真正可靠的兼容性建立在：二进制传输 + 有序枚举设计 + Schema Registry 管控 + 明确的版本发布流程之上。
