Apache Kyuubi 与 Spark 4.0 兼容性改造实践

Apache Kyuubi 作为企业级数据湖分析平台，其与 Spark 引擎的深度集成是其核心能力之一。随着 Spark 4.0 预览版的临近，Kyuubi 项目组近期完成了与 Spark 主分支的兼容性改造工作，本文将详细解析这一技术挑战的解决过程。

背景与挑战

在 Spark 4.0 的开发过程中，一个重要的架构变化是将 Web 相关组件从传统的 javax 命名空间迁移到了 jakarta 命名空间。这一变化虽然符合 Java EE 向 Jakarta EE 的演进趋势，但对于深度集成 Spark 的 Kyuubi 项目带来了显著的兼容性挑战。

Kyuubi 的日常构建中包含了对 Spark 主分支的持续集成测试，这一机制能够提前发现潜在的兼容性问题。在最近的测试中，主要暴露了两类问题：

1. 类加载问题：jakarta.servlet.Servlet 等基础类的缺失
2. ANTLR 版本冲突：Spark 4.0 升级到了 ANTLR 4.13.1，而 Kyuubi 仍在使用 4.9.3

解决方案

基础依赖调整

首先需要解决的是基础依赖问题。通过分析 Spark 4.0 的 POM 文件，确定了两个关键依赖版本：

<jakarta.servlet-api.version>5.0.0</jakarta.servlet-api.version>
<antlr4.version>4.13.1</antlr4.version>

将这些版本定义添加到 Kyuubi 的 Spark-master 配置文件中，解决了基础的类加载和 ANTLR 版本冲突问题。

命名空间冲突处理

更复杂的挑战来自于 javax 和 jakarta 命名空间的冲突。Kyuubi 中部分模块（特别是 Spark SQL 引擎）直接使用了来自 Spark WebUI 的类（如 WebUIPage、UIUtils），而这些类现在引入了 jakarta 命名空间下的类型。

针对这一挑战，项目组采用了分层解决方案：

1. 反射机制：对于核心接口，使用反射动态加载运行时类
2. Shim 层设计：引入中间适配层，隔离不同命名空间的差异
3. 条件编译：通过 Maven 配置实现不同 Spark 版本的条件编译

实现细节

在具体实现上，项目组通过一系列 PR 逐步解决了兼容性问题。其中关键技术点包括：

1. 动态类加载：对于 HttpServletRequest 等核心接口，通过反射机制在运行时确定具体实现类
2. 适配器模式：为关键接口创建适配器，统一不同命名空间下的方法签名
3. 版本感知：构建时自动检测 Spark 版本，选择正确的依赖树

成果与验证

经过系统性的改造后，Kyuubi 成功实现了：

1. 与 Spark 主分支的完全兼容
2. 保持对历史版本 Spark 的向后兼容
3. 日常构建测试全部通过

这一工作为 Kyuubi 迎接 Spark 4.0 正式版打下了坚实基础，同时也为其他基于 Spark 生态的项目提供了兼容性改造的参考范例。

经验总结

通过此次兼容性改造，我们获得了以下宝贵经验：

1. 前瞻性测试的重要性：日常构建中对主分支的测试能够提前发现问题
2. 接口隔离原则：对第三方依赖应通过适当抽象进行隔离
3. 版本兼容策略：需要建立清晰的版本兼容矩阵和测试机制

这些经验将继续指导 Kyuubi 项目未来的架构演进和技术决策。