Kyuubi项目与Apache Spark 4.0的兼容性适配实践

背景与挑战

Kyuubi作为基于Apache Spark构建的多租户SQL网关服务，其核心能力依赖于与Spark版本的深度兼容。近期Spark社区正在推进4.0.0版本的开发，其中包含了一个重大变更：将Web相关组件从javax.servlet迁移到了jakarta.servlet命名空间。这一改动直接影响了Kyuubi的日常构建测试，导致基于Spark主分支的持续集成测试持续失败。

问题分析

通过分析构建日志，我们发现主要存在两类兼容性问题：

1. 类加载问题：Spark 4.0移除了对javax.servlet的依赖，导致Kyuubi中相关代码无法找到Servlet等基础类。典型错误表现为java.lang.NoClassDefFoundError: jakarta/servlet/Servlet。

2. ANTLR版本冲突：Spark 4.0升级了ANTLR运行时版本到4.13.1，与Kyuubi原有依赖的4.9.3版本不兼容，引发序列化异常Could not deserialize ATN with version 4 (expected 3)。

解决方案

依赖版本对齐

首先需要确保基础依赖版本与Spark 4.0保持一致：

<!-- 在spark-master profile中添加 -->
<jakarta.servlet-api.version>5.0.0</jakarta.servlet-api.version>
<antlr4.version>4.13.1</antlr4.version>

命名空间适配

对于Web相关代码的适配更为复杂，需要处理javax与jakarta命名空间的冲突。我们采用了分层解决方案：

1. 反射适配层：对于核心接口差异，构建Shim中间层动态加载运行时类

public class ServletShim {
    public static Object createRequest() {
        try {
            // 优先尝试加载jakarta实现
            return Class.forName("jakarta.servlet.http.HttpServletRequest")
                      .getConstructor().newInstance();
        } catch (Exception e) {
            // 回退到javax实现
            return Class.forName("javax.servlet.http.HttpServletRequest")
                      .getConstructor().newInstance();
        }
    }
}

2. 模块隔离：对Spark WebUI的扩展代码进行重构，确保与宿主Spark版本使用相同的Servlet实现

3. 构建配置：通过Maven profile实现不同Spark版本的条件编译

<profiles>
    <profile>
        <id>spark-master</id>
        <properties>
            <servlet.namespace>jakarta</servlet.namespace>
        </properties>
    </profile>
    <profile>
        <id>spark-3.x</id>
        <properties>
            <servlet.namespace>javax</servlet.namespace>
        </properties>
    </profile>
</profiles>

实施效果

经过系列适配后，Kyuubi实现了：

• 每日构建测试全绿通过
• 同时保持对Spark 3.x系列的兼容
• 为即将到来的Spark 4.0正式版做好准备

经验总结

1. 前瞻性测试：建立针对上游主分支的日常测试能提前发现兼容性问题
2. 解耦设计：对可能变动的第三方依赖应设计适配层
3. 版本管理：明确各组件版本约束关系，避免隐式依赖
4. 渐进式迁移：重大变更应采用可回退的方案设计

该实践不仅解决了Kyuubi的特定问题，也为其他基于Spark构建的项目提供了跨大版本兼容的参考方案。未来我们将继续完善Shim层的设计，使其能够更灵活地处理类似的基础组件变更。