Java 类加载冲突实战：解决 is not an instance of

一、问题背景

在 Java Agent、Flink、插件系统等复杂运行环境中，经常会遇到同一个依赖被多个组件引入的情况。

例如，Flink 平台运行用户提交的业务 JAR，同时通过 Java Agent 上报数据血缘信息。用户业务使用 Kafka Client 2.x，而 Agent 使用 Kafka Client 3.2.3。

两套依赖可能同时存在于运行环境中，并由不同的 ClassLoader 加载。

某次创建 Kafka Producer 时，出现以下异常：

org.apache.kafka.common.KafkaException:
Failed to construct kafka producer

Caused by: org.apache.kafka.common.KafkaException:
class org.apache.kafka.common.serialization.StringSerializer
is not an instance of
org.apache.kafka.common.serialization.Serializer

乍一看，StringSerializer 明明实现了 Serializer，为什么 JVM 还认为它不是 Serializer 的实例？

核心原因是：Java 类型的身份不仅取决于类的全限定名，还取决于定义该类的 ClassLoader。

因此，同名类如果由不同的 ClassLoader 定义，在 JVM 看来就可能是完全不同的类型。

二、为什么同名类不是同一种类型？

2.1 Java 类的身份

在 Java 中，一个类的身份可以理解为：

类的身份 = 全限定类名 + 定义该类的 ClassLoader

假设运行环境中存在两个 Kafka 客户端：

Flink 运行环境
│
├── 用户业务 JAR
│   └── kafka-clients-2.x.jar
│       ├── Serializer
│       └── StringSerializer
│
└── Java Agent
    └── kafka-clients-3.2.3.jar
        ├── Serializer
        └── StringSerializer

如果用户业务的 ClassLoader 和 Agent 的 ClassLoader 分别定义了这两个版本中的 Serializer，那么：

serializerA.getClass() == serializerB.getClass()

不能仅凭类名相同就认为结果为 true。

更准确地说，下面两个类型可能并不相同：

Serializer@UserClassLoader
Serializer@AgentClassLoader

即使两个接口的包名、类名和方法签名完全相同，JVM 也不会自动将它们视为同一种类型。

2.2 为什么会出现 is not an instance of？

Kafka 创建 Producer 时，会根据配置加载 Serializer。

例如：

Properties props = new Properties();

props.put(
    "key.serializer",
    "org.apache.kafka.common.serialization.StringSerializer"
);

props.put(
    "value.serializer",
    "org.apache.kafka.common.serialization.StringSerializer"
);

KafkaProducer<String, String> producer =
    new KafkaProducer<>(props);

初始化过程中，Kafka 的配置处理逻辑会加载 Serializer 实现类，并检查它是否属于当前使用的 Serializer 接口类型。

如果加载关系如下：

KafkaProducer
    │
    └── Serializer@AgentClassLoader

StringSerializer
    │
    └── Serializer@UserClassLoader

那么即使 StringSerializer 的确实现了一个名为 Serializer 的接口，它实现的也可能是另一个 ClassLoader 定义的接口。

最终就会出现：

StringSerializer is not an instance of Serializer

需要注意，Kafka 版本不一致是可能的诱因，但真正导致该异常的是实际的类型不兼容或类加载关系冲突。版本不同不一定出错，版本相同也不代表一定不会发生类加载冲突。

三、如何定位类加载冲突？

排查时不要先升级依赖，应该先确定类究竟由谁加载。

3.1 打印关键类的 ClassLoader

在创建 Kafka Producer 前增加以下日志：

ClassLoader kafkaLoader =
        KafkaProducer.class.getClassLoader();

ClassLoader serializerLoader =
        org.apache.kafka.common.serialization.Serializer.class
                .getClassLoader();

ClassLoader contextLoader =
        Thread.currentThread().getContextClassLoader();

LOGGER.info("KafkaProducer ClassLoader: {}", kafkaLoader);
LOGGER.info("Serializer ClassLoader: {}", serializerLoader);
LOGGER.info("TCCL: {}", contextLoader);

再检查 StringSerializer 的加载来源：

Class<?> serializerClass = Class.forName(
        "org.apache.kafka.common.serialization.StringSerializer",
        false,
        Thread.currentThread().getContextClassLoader()
);

Class<?> serializerInterface =
        org.apache.kafka.common.serialization.Serializer.class;

LOGGER.info("StringSerializer ClassLoader: {}",
        serializerClass.getClassLoader());

LOGGER.info("StringSerializer source: {}",
        serializerClass.getProtectionDomain().getCodeSource());

LOGGER.info("Serializer source: {}",
        serializerInterface.getProtectionDomain().getCodeSource());

LOGGER.info("Assignable: {}",
        serializerInterface.isAssignableFrom(serializerClass));

如果 Assignable 为 false，说明通过这两个加载路径获得的类型不兼容。

如果为 true，则还需要确认 Kafka 初始化时实际加载的 Serializer 是否就是这一个类，因为 AbstractConfig 的具体加载路径可能与当前线程的 TCCL 不同。

3.2 检查是否存在多个 Kafka 客户端 JAR

检查运行目录：

find /path/to/runtime -name 'kafka-clients*.jar'

检查 Agent 是否包含 Kafka 类：

jar tf datastar-java-agent-1.0.68.jar \
  | grep 'org/apache/kafka/common/serialization/'

检查用户提交的业务 JAR：

jar tf user-job.jar \
  | grep 'org/apache/kafka/common/serialization/'

如果使用 Maven，还可以执行：

mvn dependency:tree \
  -Dincludes=org.apache.kafka:kafka-clients

需要注意，依赖树只能帮助发现依赖版本，不能证明运行时究竟加载了哪个类。最终仍要结合 ClassLoader、类来源和实际运行日志判断。

四、解决方案一：调整线程上下文类加载器

对于 Java Agent 在运行期间自行创建 Kafka Producer 的场景，可以尝试切换线程上下文类加载器（TCCL）。

原始代码：

producer = new KafkaProducer<>(kafkaProps);

修改后：

Thread thread = Thread.currentThread();
ClassLoader original = thread.getContextClassLoader();

try {
    thread.setContextClassLoader(
        KafkaProducer.class.getClassLoader()
    );

    producer = new KafkaProducer<>(kafkaProps);

} catch (Exception e) {
    LOGGER.warn("init lineage kafka producer fail", e);
} finally {
    thread.setContextClassLoader(original);
}

为什么这个方法可能有效？

Java 中，线程上下文类加载器经常用于框架、SPI 和插件机制中的动态类加载。

在某些 Kafka 初始化路径中，配置类的加载会使用 TCCL。

当 TCCL 指向用户任务的 ClassLoader 时，Kafka 初始化逻辑可能加载用户环境中的 StringSerializer。

切换 TCCL 后：

thread.setContextClassLoader(
    KafkaProducer.class.getClassLoader()
);

如果 Kafka 的配置加载逻辑使用 TCCL，且该加载器能够加载 Agent 使用的 Kafka 类，那么 Serializer 就有机会与 Producer 使用的接口保持一致。

Producer 创建完成后，再恢复原始 TCCL，避免影响后续的 Flink 用户代码。

这个方案的边界

设置 TCCL 并不等于强制所有类都从指定加载器加载。

原因包括：

1. 已经加载的类不会因为切换 TCCL 而自动重新加载。

2. 某些代码直接使用自身的定义类加载器，而不是 TCCL。

3. 父优先委派可能让指定加载器最终返回父加载器中的类。

4. Producer 初始化完成后，部分延迟加载或异步逻辑仍可能依赖 TCCL。

因此，这是一种针对特定加载路径的修复方式，而不是适用于所有类加载冲突的通用方案。

五、解决方案二：使用 Shade 隔离 Agent 依赖

如果 Agent 需要独立向 Kafka 上报日志、埋点或数据血缘信息，更适合考虑依赖隔离。

Maven Shade Plugin 可以将 Agent 使用的第三方依赖重定位到独立包名。

例如，将 Kafka 类重定位为：

org.apache.kafka
        ↓
cn.xxx.shade.kafka

示例配置：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.5.3</version>

    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>

            <configuration>
                <relocations>
                    <relocation>
                        <pattern>org.apache.kafka</pattern>
                        <shadedPattern>
                            cn.xxx.shade.kafka
                        </shadedPattern>
                    </relocation>
                </relocations>
            </configuration>
        </execution>
    </executions>
</plugin>

以上只是重定位配置示例，实际使用时需要结合 Agent 的依赖树和打包结构验证。

尤其要注意：

• Kafka 客户端内部引用的类必须保持一致的重定位关系。

• META-INF/services 中的 SPI 配置需要正确处理。

• 反射字符串、配置文件和其他第三方依赖中的类名也要检查。

• 如果 Agent 需要接收用户传入的 Kafka 类型对象，重定位后的 API 不能直接与原始 Kafka API 混用。

对于只由 Agent 内部使用的 Kafka Producer，隔离通常更容易实现。

六、解决方案三：统一依赖与类加载策略

除了修改 TCCL 和 Shade，还可以从运行架构上治理。

方案	优点	局限
切换 TCCL	改动小，适合快速验证	只影响依赖 TCCL 的加载路径
统一 Kafka 版本	依赖关系直观	可能破坏用户任务兼容性
Shade 重定位	降低 Agent 与业务依赖冲突	打包和 SPI 处理更复杂
统一类加载策略	从运行机制上控制类加载	需要评估 Flink 用户代码隔离
独立进程或服务	依赖边界清晰	增加通信和运维成本

在 Flink 平台中，用户提交的业务 JAR 属于用户运行环境，而 Agent 属于平台基础设施。

如果 Agent 的 Kafka 生产逻辑不需要直接使用用户业务中的 Kafka 类，那么应尽量避免复用用户的 Kafka 依赖。

这样既能减少版本冲突，也能避免平台基础设施受到用户任务依赖变化的影响。

七、总结

is not an instance of 并不一定意味着 Java 类没有实现对应的接口。

在多 ClassLoader 环境中，更应该关注：

1. 出错的接口和实现类分别由哪个 ClassLoader 定义。

2. 实际运行时是否存在多个版本的同名依赖。

3. 动态类加载是否使用了错误的 TCCL。

4. Agent 和用户业务 JAR 是否应该共享同一套依赖。

对于本文中的 Kafka Producer 初始化异常，可以先尝试切换 TCCL，并通过日志确认修复是否生效。

如果这是一个需要长期支持多种用户依赖版本的 Flink 平台，则应进一步考虑 Agent 依赖的 Shade 隔离和类加载边界设计。

最终原则：不要只看 JAR 版本，要看运行时实际加载的类，以及它们之间的类型关系。