Debezium 1.5配置Filter转换报错找不到EnumeratedValue类的问题

故障场景 #

• 部署环境的 Kafka Connect 镜像中，已在 /kafka/connect/debezium-connector-mysql 路径放置 debezium-scripting-1.5.0.Beta1.jar，并通过在 connect-base 镜像设置 ENABLE_DEBEZIUM_SCRIPTING=true 启用了 Debezium 脚本功能。
• 为 MySQL 源连接器配置记录过滤规则，填写的配置项为：

  "transforms": "filter",
  "transforms.filter.type": "io.debezium.transforms.Filter"
  

• 注册连接器时配置校验失败，抛出类找不到错误：

  Caused by: java.lang.ClassNotFoundException: io.debezium.config.EnumeratedValue
  at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:471)
  at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:589)
  at org.apache.kafka.connect.runtime.isolation.PluginClassLoader.loadClass(PluginClassLoader.java:104)
  at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:522)

• 对照验证：将 transforms 配置修改为 Debezium 内置的 unwrap 转换后，同类类加载报错不再出现。

根因分析 #

• 报错提示的 io.debezium.config.EnumeratedValue 是 Debezium 核心包的通用配置枚举类，并非类本身缺失，问题出在 Kafka Connect 的插件类加载隔离规则：
  1. io.debezium.transforms.Filter 这个记录过滤器类，本身存在对 Debezium 核心包的依赖，而当前插件目录下仅放置了轻量的 debezium-scripting 扩展包，这个包本身不包含核心配置类的实现代码。
  2. 切换到 unwrap 转换后报错消失，是因为 unwrap 对应的实现类 ExtractNewRecordState 原本就打包在 MySQL 连接器的主依赖包中，类加载器能顺着主包的类路径找到同依赖的核心枚举类，自然不会触发类找不到异常。
  3. Kafka Connect 默认对每个插件目录下的 jar 做独立类加载隔离，当指定 io.debezium.transforms.Filter 为转换类时，类加载器会仅扫描当前插件目录下的 jar 来找依赖类，自然会因为目录内没有核心包抛出 ClassNotFoundException。
• 版本错位是额外诱发因素：使用的 debezium-scripting-1.5.0.Beta1 是预发布版本，和正式发布的 MySQL 连接器版本的核心包路径、类引用关系本身存在偏差，进一步提升了类加载失败的概率。

可落地修复方案 #

• 补齐匹配版本的核心依赖
  • 下载和 debezium-scripting-1.5.0.Beta1 版本完全一致的 debezium-core-1.5.0.Beta1.jar，放置到 /kafka/connect/debezium-connector-mysql 插件目录下，重启 Kafka Connect 进程，等待插件扫描完成后再重新注册连接器。
• 换用扩展包自带的脚本过滤实现
  • 跳过存在跨包依赖的 io.debezium.transforms.Filter 类，直接使用 scripting 包内置的脚本转换类实现过滤逻辑。这个类的所有依赖都在 scripting 包和 groovy 依赖中，不会触发跨包类加载问题，参考配置：

    transforms=filter
    transforms.filter.type=io.debezium.transforms.ScriptingTransformation
    transforms.filter.language=groovy
    # 示例规则：过滤所有删除操作产生的 tombstone 事件，可根据实际过滤需求调整脚本逻辑
    transforms.filter.filter.script="return record.operation() != 'd' || record.value() != null"
    

• 调整类加载隔离策略
  • 修改 Kafka Connect 的 plugin.path 配置，将所有 Debezium 相关的 jar 统一放到同一个独立的插件目录下，不再把扩展包和连接器包拆到不同的隔离目录，让所有类加载器共享公共类路径，从规则层面避免单目录扫描导致的类缺失问题。

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