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

Apache Kyuubi 作为企业级数据湖分析平台，其与 Spark 引擎的兼容性一直是社区关注的重点。近期，随着 Spark 4.0 预览版的临近，Kyuubi 社区针对 Spark 主分支的兼容性问题进行了系统性的改造工作。本文将深入剖析这一技术挑战的解决过程。

问题背景

Kyuubi 项目通过每日构建（Daily Build）机制持续验证与 Spark 主分支的兼容性。在近期测试中，发现了两个关键问题：

1. Jakarta Servlet API 兼容性问题：Spark 4.0 将 Web 相关组件从传统的 javax.servlet 迁移到了 jakarta.servlet 命名空间，导致 Kyuubi 中依赖 javax.servlet 的代码无法编译。

2. ANTLR 版本冲突：Spark 4.0 升级了 ANTLR 版本至 4.13.1，而 Kyuubi 仍使用 4.9.3 版本，产生了运行时版本不匹配问题。

技术挑战分析

兼容性改造面临的核心挑战在于：

1. 双向兼容需求：Kyuubi 需要同时支持新旧版本的 Spark，不能简单地通过升级依赖解决问题。

2. Web 组件深度耦合：Kyuubi 的 WebUI 模块直接使用了 Spark 提供的 WebUIPage、UIUtils 等类，这些类内部又依赖 Servlet API，形成了复杂的依赖链。

3. API 不兼容：javax 和 jakarta 命名空间下的类虽然功能相似，但属于完全不同的类路径，无法通过简单的类型转换解决。

解决方案

社区采用了分层解决的策略：

1. 依赖版本统一

对于 ANTLR 这类纯技术组件，采用版本对齐策略：

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

2. 适配层设计

针对 Servlet API 的命名空间变更，创新性地引入了 Shim（垫片）适配层模式：

public class ServletShim {
  public static HttpServletRequest wrap(Object request) {
    if (request instanceof jakarta.servlet.http.HttpServletRequest) {
      return new JakartaRequestWrapper((jakarta.servlet.http.HttpServletRequest) request);
    } else {
      return (javax.servlet.http.HttpServletRequest) request;
    }
  }
  
  private static class JakartaRequestWrapper implements HttpServletRequest {
    private final jakarta.servlet.http.HttpServletRequest delegate;
    
    // 实现所有接口方法，委托给delegate
  }
}

这种设计实现了：

• 编译时统一接口
• 运行时动态适配
• 新旧版本无缝切换

3. 模块化改造

将受影响的组件划分为：

• 核心引擎模块：保持最小依赖
• WebUI 扩展模块：实现版本适配
• 插件模块：按需加载适配器

实施效果

经过系列改造后：

1. 每日构建恢复绿色状态
2. 支持 Spark 3.x 和 4.0 双版本
3. 为后续大版本升级奠定基础

经验总结

1. 前瞻性测试：每日构建机制能及早发现兼容性问题
2. 解耦设计：核心模块应尽量减少对特定实现的依赖
3. 适配器模式：是解决版本差异的有效手段
4. 渐进式升级：通过条件编译和动态加载平滑过渡

这次改造不仅解决了具体的技术问题，更为 Kyuubi 社区积累了处理重大版本升级的宝贵经验，展现了开源社区协同解决复杂技术挑战的能力。