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

Apache Kyuubi 作为企业级数据湖分析平台，其核心功能之一是提供与 Spark 的深度集成。随着 Spark 4.0 预览版的临近，Kyuubi 项目组面临一个重要挑战：如何确保与 Spark 主分支的兼容性。本文将详细解析这一兼容性改造的技术实现过程。

兼容性问题背景

在 Spark 4.0 的开发过程中，一个重大变化是将 Web 相关组件从传统的 javax 命名空间迁移到了 jakarta 命名空间。这种底层架构的变更导致了 Kyuubi 的日常测试在 Spark 主分支上持续失败。具体表现为：

1. 类加载失败：jakarta.servlet.Servlet 类无法找到
2. ANTLR 版本冲突：运行时版本与编译版本不匹配
3. 命名空间冲突：javax 和 jakarta 的 Web 相关类不兼容

关键技术挑战

1. 依赖版本管理问题

Spark 4.0 引入了两个关键依赖的版本变更：

• jakarta.servlet-api 升级到 5.0.0
• ANTLR 升级到 4.13.1

解决方案是在 Kyuubi 的 Maven 配置中为 Spark 主分支专门添加对应的 profile，显式声明这些依赖版本。

2. 命名空间冲突

这是最复杂的挑战。Kyuubi 的部分代码直接使用了 javax.servlet 相关类，而 Spark 4.0 已全面转向 jakarta.servlet。这种不兼容性体现在多个方面：

• 类型不匹配：HttpServletRequest 等类的全限定名变更
• Web UI 组件：EnginePage 和 EngineSessionPage 等页面类的方法签名不兼容
• Python 执行相关：javax.ws 包下的类无法找到

系统化解决方案

1. 依赖隔离策略

通过 Maven 的 profile 机制，为不同 Spark 版本提供不同的依赖配置。对于 Spark 主分支：

<profile>
  <id>spark-master</id>
  <properties>
    <jakarta.servlet-api.version>5.0.0</jakarta.servlet-api.version>
    <antlr4.version>4.13.1</antlr4.version>
  </properties>
</profile>

2. 反射式兼容层

针对命名空间冲突问题，我们采用了"Shim"（兼容层）设计模式。核心思想是通过反射动态绑定运行时类，实现不同版本间的透明调用。基本结构如下：

package shim;

class WebComponentShim {
  public Object createRequestWrapper(Object rawRequest) {
    // 通过反射检查运行时环境
    if (isJakartaEnv()) {
      return new JakartaRequestWrapper(rawRequest);
    } else {
      return new JavaxRequestWrapper(rawRequest);
    }
  }
  
  // 其他兼容方法...
}

3. 模块化改造

将受影响的组件划分为独立模块，特别是：

• Spark SQL 引擎模块
• 血缘解析扩展模块
• Web UI 相关组件

每个模块针对不同 Spark 版本提供适配实现，通过 Maven 的依赖范围控制确保正确的实现被加载。

实施效果

经过系统化改造后：

1. 日常构建成功通过 Spark 主分支的兼容性测试
2. 保持了对现有 Spark 版本（3.x）的完全兼容
3. 为 Spark 4.0 的正式发布做好了准备

经验总结

1. 前瞻性测试：建立针对上游主分支的日常测试机制能及早发现问题
2. 隔离设计：关键组件应预先考虑版本隔离，避免硬编码依赖
3. 反射慎用：虽然反射解决了兼容性问题，但需要良好的封装和文档说明
4. 自动化验证：兼容性改造需要完善的测试覆盖，包括正向和反向用例

这次改造不仅解决了眼前的问题，更重要的是为 Kyuubi 建立了可持续的跨版本兼容机制，为后续支持更多 Spark 版本奠定了坚实基础。