Apache Pinot Spark连接器依赖冲突问题分析与解决方案

背景介绍

Apache Pinot是一个实时分布式OLAP数据存储系统，其Spark连接器允许用户直接从Spark环境中查询Pinot数据。在最新开发版本中，开发者发现当使用Spark 3.5.0环境时，连接器会出现类加载失败的问题，导致无法正常查询数据。

问题现象

在Databricks Runtime 15.4 LTS（包含Spark 3.5.0和Scala 2.12）环境中，使用Java 17运行Pinot Spark连接器时，系统抛出以下异常：

java.lang.NoClassDefFoundError: Could not initialize class io.circe.Decoder$

进一步分析堆栈跟踪发现，根本原因是cats库的版本冲突：

Caused by: java.lang.ExceptionInInitializerError: Exception java.lang.NoSuchMethodError: 'void cats.kernel.CommutativeSemigroup.$init$(cats.kernel.CommutativeSemigroup)'

问题分析

1. 依赖关系链：

   • Pinot连接器使用了circe-generic库（版本0.14.12）来处理Pinot API的JSON响应
   • circe-generic依赖cats库
   • Spark运行环境本身可能已经包含不同版本的cats库

2. 冲突本质：

   • 这是典型的"依赖地狱"问题，两个不同版本的cats库在运行时发生冲突
   • cats库在Scala生态中广泛使用，容易发生版本不兼容
   • 二进制兼容性问题导致CommutativeSemigroup类的初始化方法找不到

3. 影响范围：

   • 主要影响使用较新Spark版本的环境
   • 在包含预装cats库的分布式环境中问题尤为明显
   • 使用Java 17运行时环境时更容易暴露此问题

解决方案

经过深入分析，团队提出了以下解决方案：

1. 移除circe依赖：

   • 识别到circe仅用于简单的JSON解码
   • 项目中已包含Jackson库，可以完成相同功能
   • 用Jackson替换circe可以避免引入额外依赖

2. 具体实施：

   • 重写PinotClusterClient中的JSON处理逻辑
   • 使用Jackson的ObjectMapper替代circe的Decoder
   • 保持API响应解析的功能不变

3. 优势：

   • 不增加新的依赖项
   • Jackson已是Pinot项目的核心依赖，兼容性有保障
   • 减少二进制冲突风险
   • 简化项目的依赖树

经验总结

1. 依赖管理最佳实践：

   • 在库开发中应尽量减少第三方依赖
   • 优先使用项目已有的依赖项
   • 特别注意Scala库的版本兼容性

2. Spark连接器开发注意：

   • 需要考虑运行环境的依赖状况
   • 尽量使用广泛兼容的库
   • 复杂依赖应该考虑shade重定位

3. 问题排查方法：

   • 通过完整堆栈分析根本原因
   • 理解各依赖项的关系
   • 考虑运行环境的特殊性

这个案例展示了在复杂分布式系统中处理依赖冲突的典型思路，也为开发稳定的Spark连接器提供了有价值的参考。通过这次修复，Pinot Spark连接器在各类环境中的兼容性得到了显著提升。