Kafka配置auto.register.schemas=false报Schema not found解决方案

auto.register.schemas=false模式下序列化抛出SerializationException、放开配置就自动生成新Schema，核心原因是：序列化器本地持有的Avro Schema，和提前注册到Schema Registry中的Schema无法精确匹配。

Kafka Avro序列化器在禁止自动注册的逻辑中，不会主动将本地Schema推送到Registry，而是先对本地Schema做规范化计算得到哈希指纹，再去Registry查询该指纹绑定的Schema ID，查询无结果就直接抛出异常；放开自动注册配置后，序列化器发现指纹不存在就会直接把本地Schema作为新版本提交，就会出现新增Schema、无法复用预注册版本的现象。

常见的匹配失败触发点：

• 手动注册的Schema内容和代码生成实体类对应的Schema存在细微差异（字段顺序、命名空间、默认值、doc注释、类型定义任意一处不匹配都会导致哈希校验失败）
• Subject命名策略不匹配，序列化器查找的Subject路径和实际注册路径不一致
• 客户端kafka-avro-serializer依赖版本和Schema Registry服务端版本不兼容，Schema规范化计算逻辑存在差异
• 注册Schema时使用的Subject名不符合序列化器默认命名规则

1. 校验两端Schema一致性 #

先确认本地代码生成类对应的Schema和Registry中预存的Schema完全一致：

• 拉取Registry中users-value Subject下的最新Schema，直接调用本地接口获取：

curl http://localhost:8085/subjects/users-value/versions/latest

• 在项目中打印生成的Avro实体类对应的原始Schema，以User类为例：

println(User.getClassSchema().toString(true))

• 逐字对比两份Schema内容，重点核对命名空间、字段顺序、字段类型、默认值、doc注释、别名配置，任意一处不一致都会导致匹配失败。如果存在差异，直接将项目中avsc源文件的全量内容覆盖注册到users-value Subject下，不要手动修改注册内容。

2. 补全Kafka配置参数 #

application.yml中生产者配置需要补全策略相关参数，避免默认逻辑和预期不一致：

spring:
  kafka:
    producer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: io.confluent.kafka.serializers.KafkaAvroSerializer
      properties:
        schema.registry.url: http://localhost:8085
        auto.register.schemas: false
        # 注册Schema时如果用的是默认TopicNameStrategy，保持以下配置即可；如果用了RecordNameStrategy/TopicRecordNameStrategy，替换为对应策略类全限定名
        value.subject.name.strategy: io.confluent.kafka.serializers.subject.TopicNameStrategy
        # 开启后直接拉取对应Subject下的最新可用版本做序列化，跳过本地Schema哈希匹配校验，适配预注册Schema场景
        use.latest.version: true

注意：消费端的反序列化器配置要和生产者保持相同的Subject命名策略，否则消费时也会出现Schema找不到的问题

3. 对齐依赖与插件配置 #

首先确认build.gradle中引入的kafka-avro-serializer版本，和docker-compose中部署的Schema Registry版本完全一致，跨版本会存在Schema计算逻辑不兼容的问题。
davidmc24 Gradle Avro插件参考配置如下，不要开启会修改Schema结构的可选配置：

plugins {
    id "com.github.davidmc24.gradle.plugin.avro" version "1.9.1"
    id "org.springframework.boot" version "3.2.0"
    id "org.jetbrains.kotlin.jvm" version "1.9.20"
}
dependencies {
    implementation "org.apache.avro:avro:1.11.3"
    implementation "io.confluent:kafka-avro-serializer:7.5.1" // 版本和服务端Schema Registry对齐
}
avro {
    fieldVisibility = "PRIVATE"
    dateTimeLogicalType = "JSR310"
    // 不要开启自动生成额外方法、修改字段命名的配置，避免生成类对应的Schema发生变化
}

4. 验证结果 #

重启服务后先查询Schema Registry中users-value的版本列表，确认没有新增版本，再调用消息发送接口，此时不会抛出序列化异常，也不会自动注册新的Schema版本。

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