Confluent Schema Registry JSON Schema兼容性模式下字段可选性判定问询

一、三种兼容性模式对自动派生Schema的生效逻辑 #

Kafka Schema Registry的三种兼容性规则，是基于自动生成的JSON Schema的结构（字段必填性、类型）来校验版本间的兼容性：

• Backward兼容：新Schema必须能被旧消费者解析。自动生成Schema时，新增字段必须是可选的；不能删除旧Schema中的必填字段；类型变更只能是兼容方向（比如int转long）。旧消费者没有处理新字段的逻辑，所以新字段必须可选，否则会抛出解析错误。
• Forward兼容：旧Schema必须能被新消费者解析。自动生成Schema时，删除的字段必须是可选的；不能新增必填字段；类型变更不能破坏旧数据的解析。新消费者需要适配旧数据中缺失的字段，所以被删除的字段必须是可选的。
• Full兼容：同时满足Backward和Forward规则，允许双向兼容的变更。自动生成Schema时，新增/删除的字段都必须是可选的，类型变更也得是双向兼容的（比如long和int互转）。

二、Schema Registry如何识别可选字段 #

KafkaJsonSchemaSerializer是从Java对象的字段特性推导JSON Schema的可选性，核心判断依据如下：

• 字段的可空性：这是最关键的判定标准：
  • 如果Java字段是Optional类型、带有@Nullable注解，或者是未初始化的引用类型（默认允许为null），生成的JSON Schema会将该字段标记为"nullable": true，且不会加入Schema的required数组——这就是Schema Registry认定为“可选字段”的核心标志。
  • 若Java字段是基本类型（如int、boolean）且没有显式允许null（比如没包装成Integer），生成的Schema会将其加入required数组，视为必填字段。
    举个代码示例：

  public class Order {
      private String orderId; // 引用类型，默认可空→Schema中为可选
      private Optional<String> buyerName; // Optional类型→Schema中为可选
      @Nullable private Integer totalAmount; // 带@Nullable→Schema中为可选
      private final int status = 0; // 基本类型+默认值→Schema中为必填
  }
  

  对应生成的JSON Schema里，orderId、buyerName、totalAmount都不在required数组内，属于可选字段；status则会出现在required数组中，是必填项。
• 序列化器配置：默认开启json.schema.generate.for.nullables=true，会正确将可空字段标记为可选；如果关闭该配置，可空字段会被强制标记为必填，这会直接破坏兼容性规则，不建议修改。
• 默认值的影响：字段有默认值（比如基本类型的默认值或显式赋值）会辅助提升兼容性，但不是判定可选的直接依据——即使有默认值，只要字段不允许为null，依然会被标记为必填。

三、Full模式下可选字段的操作逻辑 #

Full模式允许添加或删除可选字段，本质是因为这类字段在Schema的required数组之外：

• 添加可选字段时，旧消费者解析新数据时会自动忽略该字段，不会报错；
• 删除可选字段时，新消费者解析旧数据时，因为该字段不是必填，会用null或默认值填充，不会抛出解析异常。

内容的提问来源于stack exchange，提问作者mihais