Spring Boot 3 集成 Apache Calcite 实践：动态数据管理与统一SQL查询

在实际业务开发中，多数据源并存是常态。例如，订单数据存在MySQL，库存数据使用PostgreSQL，而用户行为数据可能存储在MongoDB中。面对这种异构数据环境，进行统一的关联查询与分析往往会变得异常复杂。

本文将介绍如何利用 Apache Calcite 这一动态数据管理框架，与 Spring Boot 3 进行深度集成，提供一个高效、统一的多数据源查询解决方案。

一、核心认知：Apache Calcite 为何是多数据源查询的利器？

在动手集成前，需要先理解其核心逻辑：Calcite 如何成为处理异构数据查询的“万能钥匙”？

1.1 不止是查询引擎：Calcite的核心定位

Apache Calcite 的本质是一个 动态数据管理框架 ，而非传统的数据库。其核心价值在于“解耦”——将数据存储与数据查询逻辑分离。无论数据存储在何处、是何种格式，都能通过统一的 SQL 接口进行查询。

通俗地讲，Calcite 扮演着“数据翻译官”的角色。你只需要编写标准的 SQL 语句，它就能将其翻译成底层各个数据源能够理解的指令，执行后将结果整合成统一的格式返回。这正是它能够优雅处理多数据源查询的核心机制。

1.2 Calcite的核心能力拆解

• 统一 SQL 接口：支持标准 SQL（ANSI SQL）。无论底层是关系型数据库（如 MySQL、PostgreSQL）、非关系型数据库（如 MongoDB、Redis），还是文件（CSV、Parquet）或大数据引擎（Hive、Spark），都能通过同一套 SQL 进行查询。
• 强大的查询优化：内置基于规则和成本的查询优化器，能自动优化 SQL 执行计划，提升查询效率。在复杂的多表关联、跨数据源查询场景下，优化效果尤为明显。
• 灵活的数据源适配：通过“适配器（Adapter）”机制来连接不同数据源。社区已提供了大量现成适配器，同时也支持自定义开发以适配特殊数据源。
• 轻量级集成：核心依赖体积小，无复杂依赖链，可轻松集成到 Spring Boot 等主流 Java 开发框架中，无需单独部署服务（当然也支持独立部署）。

二、重点实战：Spring Boot 3 集成 Calcite 核心步骤

本节将聚焦 Calcite 与 Spring Boot 3 集成的核心环节，包含完整代码和关键注意事项。

2.1 核心依赖引入

首先，在项目的 pom.xml 文件中引入必要的依赖，包括 Calcite 核心包、数据源适配器以及 MyBatis Plus。

<!-- Calcite核心依赖 -->
<dependency>
    <groupId>org.apache.calcite</groupId>
    <artifactId>calcite-core</artifactId>
    <version>1.36.0</version>
</dependency>

<!-- MySQL适配器（用于适配MySQL数据源） -->
<dependency>
    <groupId>org.apache.calcite</groupId>
    <artifactId>calcite-mysql</artifactId>
    <version>1.36.0</version>
</dependency>

<!-- MongoDB适配器（用于适配MongoDB数据源） -->
<dependency>
    <groupId>org.apache.calcite</groupId>
    <artifactId>calcite-mongodb</artifactId>
    <version>1.36.0</version>
</dependency>

<!-- Spring Boot 与 MyBatis Plus 集成核心依赖 -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.5</version> <!-- 适配Spring Boot 3的稳定版 -->
</dependency>

<!-- 数据库连接池依赖（MyBatis Plus需连接池支持） -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>druid-spring-boot-starter</artifactId>
    <version>1.2.20</version>
</dependency>

避坑点强调：

1. Calcite 核心依赖与所有适配器的版本必须保持一致，否则可能引发类加载异常。
2. MyBatis Plus 需选择明确支持 Spring Boot 3 的版本（建议 3.5.3+）。
3. 必须引入连接池依赖，否则 Calcite 数据源无法被 MyBatis Plus 正常管理。

2.2 核心配置：Calcite 模型文件编写

模型文件（JSON格式）是 Calcite 识别和配置数据源的关键。通常将其置于 resources 目录下，命名为 calcite-model.json。以下是一个同时配置 MySQL 和 MongoDB 数据源的示例：

{
  "version": "1.0",
  "defaultSchema": "ecommerce",
  "schemas": [
    {
      "name": "ecommerce",
      "type": "custom",
      "factory": "org.apache.calcite.adapter.jdbc.JdbcSchema$Factory",
      "operand": {
        "jdbcUrl": "jdbc:mysql://localhost:3306/ecommerce_order?useSSL=false&serverTimezone=UTC",
        "username": "root",
        "password": "123456",
        "driver": "com.mysql.cj.jdbc.Driver"
      }
    },
    {
      "name": "user_mongo",
      "type": "custom",
      "factory": "org.apache.calcite.adapter.mongodb.MongoSchema$Factory",
      "operand": {
        "host": "localhost",
        "port": 27017,
        "database": "user_db",
        "collection": "user_info"
      }
    }
  ]
}

关键配置说明：

• defaultSchema：指定默认查询的 Schema，查询时可省略 Schema 前缀。
• factory：对应数据源的适配器工厂类，Calcite 已为主流数据源提供现成实现。
• operand：数据源连接参数，根据类型不同而有所差异（如 MySQL 的 jdbcUrl，MongoDB 的 host/port）。

2.3 Spring Boot 集成 Calcite + MyBatis Plus 核心配置

此步骤是集成的核心，目标是配置 Calcite 数据源，并使其被 MyBatis Plus 使用。

import com.baomidou.mybatisplus.annotation.DbType;
import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
import org.apache.calcite.jdbc.CalciteConnection;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.support.PathMatchingResourcePatternResolver;
import org.springframework.jdbc.datasource.DataSourceTransactionManager;
import org.springframework.transaction.PlatformTransactionManager;

import javax.sql.DataSource;
import java.sql.Connection;
import java.sql.DriverManager;
import java.util.Properties;

@Configuration
@MapperScan(basePackages = "com.example.calcite.mapper") // 扫描Mapper接口
public class CalciteMybatisPlusConfig {

    // 1. 配置Calcite数据源
    @Bean
    public DataSource calciteDataSource() throws Exception {
        Properties props = new Properties();
        props.setProperty("model", "classpath:calcite-model.json");
        Connection connection = DriverManager.getConnection("jdbc:calcite:", props);
        CalciteConnection calciteConnection = connection.unwrap(CalciteConnection.class);
        return calciteConnection.getDataSource();
    }

    // 2. 配置MyBatis Plus的SqlSessionFactory，指定使用Calcite数据源
    @Bean
    public SqlSessionFactory sqlSessionFactory(DataSource calciteDataSource) throws Exception {
        MybatisSqlSessionFactoryBean sessionFactory = new MybatisSqlSessionFactoryBean();
        // 注入Calcite数据源
        sessionFactory.setDataSource(calciteDataSource);
        // 配置mapper.xml文件路径（如果使用XML方式）
        sessionFactory.setMapperLocations(
                new PathMatchingResourcePatternResolver()
                        .getResources("classpath:mapper/*.xml"));
        // 配置MyBatis全局参数（可选）
        org.apache.ibatis.session.Configuration configuration = new org.apache.ibatis.session.Configuration();
        configuration.setMapUnderscoreToCamelCase(true); // 下划线转驼峰
        sessionFactory.setConfiguration(configuration);
        // 注入MyBatis Plus插件
        sessionFactory.setPlugins(mybatisPlusInterceptor());
        return sessionFactory.getObject();
    }

    // 3. MyBatis Plus分页插件
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); // 适配Calcite兼容的MySQL语法
        return interceptor;
    }

    // 4. 配置事务管理器（可选）
    @Bean
    public PlatformTransactionManager transactionManager(DataSource calciteDataSource) {
        return new DataSourceTransactionManager(calciteDataSource);
    }
}

核心逻辑：首先通过 Calcite 的 JDBC 驱动创建出一个统一的数据源，该数据源背后关联了模型文件中定义的所有异构数据源。然后将此数据源注入到 MyBatis Plus 的 SqlSessionFactory 中。自此，后续的数据访问操作将完全遵循 MyBatis Plus 的编程模式，而跨数据源查询的复杂性则由 Calcite 在底层处理。

2.4 核心查询实现（MyBatis Plus风格）

以下通过一个跨 MySQL 订单表和 MongoDB 用户表的关联查询示例，演示如何使用 MyBatis Plus 进行查询。

1. 定义实体类（对应跨数据源查询结果）

   import lombok.Data;
   import java.math.BigDecimal;
   
   @Data
   public class UserOrderVO {
       private String orderId;     // 订单ID（来自MySQL）
       private String orderTime;   // 下单时间（来自MySQL）
       private BigDecimal amount;  // 订单金额（来自MySQL）
       private String userName;    // 用户名（来自MongoDB）
       private String phone;       // 手机号（来自MongoDB）
       private String userId;      // 用户ID（关联字段）
   }

2. 定义Mapper接口

   import com.baomidou.mybatisplus.core.mapper.BaseMapper;
   import org.apache.ibatis.annotations.Param;
   import org.apache.ibatis.annotations.Select;
   import java.util.List;
   
   public interface UserOrderMapper extends BaseMapper<UserOrderVO> {
       // 使用注解方式编写跨数据源关联SQL
       @Select("SELECT " +
               "o.order_id AS orderId, o.order_time AS orderTime, o.amount, " +
               "u.user_name AS userName, u.phone, o.user_id AS userId " +
               "FROM ecommerce.order o " + // ecommerce: MySQL的Schema；order: 订单表
               "JOIN user_mongo.user_info u " + // user_mongo: MongoDB的Schema；user_info: 用户表
               "ON o.user_id = u.user_id " +
               "WHERE o.user_id = #{userId}")
       List<UserOrderVO> queryUserOrderByUserId(@Param("userId") String userId);
   }

3. 编写Service层

   import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
   import org.springframework.stereotype.Service;
   import java.util.List;
   
   @Service
   public class UserOrderServiceImpl extends ServiceImpl<UserOrderMapper, UserOrderVO> implements UserOrderService {
       @Override
       public List<UserOrderVO> getUserOrderByUserId(String userId) {
           // 调用Mapper接口方法，实现跨数据源查询
           return baseMapper.queryUserOrderByUserId(userId);
       }
   }

4. 编写Controller层

   import org.springframework.beans.factory.annotation.Autowired;
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.PathVariable;
   import org.springframework.web.bind.annotation.RestController;
   import java.util.List;
   
   @RestController
   public class CrossDataSourceQueryController {
       @Autowired
       private UserOrderService userOrderService;
   
       @GetMapping("/user/order/{userId}")
       public List<UserOrderVO> queryUserOrder(@PathVariable String userId) {
           return userOrderService.getUserOrderByUserId(userId);
       }
   }

实现要点：

• 实体类字段需与 SQL 查询结果集的列名（或别名）对应，利用别名可方便地进行下划线到驼峰的映射。
• Mapper 接口继承 BaseMapper 后，可直接使用 MyBatis Plus 提供的分页、条件构造器等丰富功能。
• 编写的 SQL 是标准语法，Calcite 负责将其解析并适配到底层不同的数据源，对开发者透明。

三、深度解析：Calcite 的经典使用场景

掌握集成步骤后，理解其典型应用场景能让技术更好地服务于业务。

场景一：多系统数据融合查询
这是企业级数据中台的常见需求。在大型企业中，数据常分散于多个系统：订单系统用 MySQL，用户系统用 MongoDB 存储行为数据，库存系统用 PostgreSQL。传统方式需要分别调用各系统接口，在业务层手动拼接数据，效率低且易出错。使用 Calcite 分别适配这些数据源后，仅需一条标准 SQL 即可实现跨数据源关联查询。业务层无需关心数据物理存储位置，可专注于核心逻辑，显著提升开发效率。Calcite 的查询优化器还能自动优化关联执行计划。

场景二：实时与离线数据联动查询
电商等领域常需同时分析实时数据与历史数据。例如，实时订单流存在于 Kafka，历史订单数据存在于 Hive 中。运营需要查询“今日实时订单+近30天历史订单”的汇总数据。利用 Calcite 的 Kafka 适配器和 Hive 适配器，可以将流数据与离线数据纳入同一查询体系，通过一条 SQL 完成联合查询。这避免了繁琐的数据同步过程，兼顾了实时性与历史分析的完整性。

场景三：自定义数据源与文件直接查询
企业内存在大量 CSV、Excel、Parquet 等格式的文件数据。传统方法是先将其导入数据库再进行查询，流程冗长。Calcite 内置了文件适配器，支持直接查询这些文件数据，无需导入。结合 Spring Boot 的文件上传功能，甚至可以实现“文件上传后立即用 SQL 查询”的临时数据分析需求。对于内部特殊的二进制数据格式，可以通过实现 Calcite 的 SchemaFactory 和 TableFactory 接口来自定义适配器。

四、避坑指南：集成注意事项与优化建议

4.1 常见问题与规避方法

• 版本一致性：务必确保 Calcite 核心依赖与所有数据源适配器（calcite-mysql, calcite-mongodb 等）的版本号完全一致，否则极易引发类冲突。
• 模型文件配置：Schema 和表名需定义清晰且唯一。数据源的连接参数（URL、端口、认证信息）必须准确无误，任何错误都会导致连接失败。
• 性能瓶颈意识：跨数据源查询的整体性能受限于响应最慢的那个数据源。务必确保每个独立数据源自身的性能和稳定性。

4.2 性能优化建议

• 启用缓存：合理配置 Calcite 的元数据缓存和查询计划缓存，可以减少重复解析 SQL 和获取元数据的开销，提升重复查询的响应速度。
• SQL 编写优化：尽量避免过于复杂的嵌套查询和笛卡尔积。在编写 SQL 时，可以有意识地将过滤条件下推（Pushdown），尽管 Calcite 优化器会尝试自动下推，但明确的写法有助于生成更优计划。
• 自定义优化规则：对于极其复杂的业务查询模式，可以考虑实现 Calcite 的 RelOptRule 接口，编写自定义的优化规则，以针对特定场景进行深度优化。

五、总结

对于 Spring Boot 3 开发者而言，集成 Apache Calcite 的关键在于理解其“统一查询”的核心思想。通过正确配置模型文件、在 Spring 中配置好核心 Bean，即可快速为应用赋予强大的多数据源查询能力。这种方式将异构数据源的访问复杂性屏蔽在底层，使开发者能够使用熟悉的 SQL 和 MyBatis Plus 范式进行开发，大幅提升了开发效率与系统可维护性。

希望本文的实践指南能帮助你解决多数据源查询的难题。如果你想深入探讨更多关于架构设计或数据处理的话题，欢迎在云栈社区与更多的开发者进行交流。