用 Quidem 为 Apache Druid 编写 SQL 级测试:录制驱动、Broker 抓包与 .iq 用例全流程指南

原创2026-09-23 10:02:171,359 阅读
文章标签:数据库OLAP大数据后端

用 Quidem 为 Apache Druid 编写 SQL 级测试:录制驱动、Broker 抓包与 .iq 用例全流程指南

导读

本文以 Apache Druid 仓库中的 quidem-ut 模块(quidem-ut/README.md)为骨架,系统讲解如何借助 Quidem 框架"轻松编写 SQL 级测试":既可以直接针对现有测试后端 ComponentSupplier 编写 .iq 用例,把测试用例贴近被测代码,也可以启动一个内置的录制型 Broker,在真实 SQL 执行链路上"抓包"生成测试文件。读完本文,你将掌握 quidem-ut 的环境搭建、构建与启动命令、quidem.uri/quidem.record.autostart 等关键参数、录制与回放工作流,以及覆盖更新、筛选执行等日常维护手段,并理解其底层如何通过 Druid SQL Hook 与 Jetty 资源实现"即查即录"。

什么是 Quidem,为什么 Druid 需要它

Quidem 是 Apache Calcite 生态中一种基于文本文件的 SQL 测试框架:每个测试用例是一个 .iq 文件,文件中同时包含 SQL 语句与期望结果集,!use、!set、!ok 等命令控制执行语义。测试运行时,Quidem 连接被测系统,执行文件中的语句并把实际输出与文件内的期望结果比对。

在 Druid 中,quidem-ut(Maven artifact 为 druid-quidem-ut,见 quidem-ut/pom.xml)把这一模式与 Druid 的 SQL 测试框架 SqlTestFramework 打通。其核心价值正如 quidem-ut/README.md 所述:

  • 轻松编写 SQL 级测试:无需手写大量 Java 测试代码,一条 SQL 加一份期望结果即可成为测试。
  • 复用现有测试后端:测试可以基于已有的 ComponentSupplier(即 SqlTestFramework 的组件供给器)运行,从而把测试用例"移动到更贴近被测代码的位置"。

换句话说,quidem-ut 是 Druid 在"单元测试"(DruidQuidemTestBase 驱动 .iq 文件)与"服务级测试"(把测试后端伪装成一个真实 Broker 供外部查询)之间架起的一座桥。

环境准备:安装 Java 与 Maven

开始之前需要 JDK 与 Maven。文档给出了通过 sdkman 安装的推荐路径:

# 安装 sdkman
curl -s "https://get.sdkman.io" | bash
# 安装结束后:要么新开一个终端,要么按安装完成时的提示执行

# 安装 java 与 maven
sdk install java 11.0.23-zulu
sdk install maven

# 验证 mvn 可用
mvn --version

# 下载 druid 源码(FIXME:合入主仓库前需改为正式仓库/分支)
git clone --branch quidem-record https://github.com/kgyrtkirk/druid

说明两点:

  1. git clone --branch quidem-record 是模块开发期的示例命令,README 中标注了 FIXME;在当前仓库中,quidem-ut 已作为标准 Maven 模块随项目一起构建,quidem-ut/pom.xml 的父 POM 为 org.apache.druid:druid:31.0.0-SNAPSHOT,直接使用本仓库即可,无需单独克隆其他分支。
  2. 仓库当前父 POM 版本为 31.0.0-SNAPSHOT(见 quidem-ut/pom.xml),请确保本机 JDK 版本与该版本构建要求匹配(README 示例选用 JDK 11)。

构建与运行测试

构建模块

由于 quidem-ut 依赖大量核心与扩展模块(druid-sql、druid-processing、druid-server、druid-indexing-service、druid-datasketches、druid-kafka-indexing-service、druid-multi-stage-query 等,均以 31.0.0-SNAPSHOT 引用),需要先构建项目。README 给出的命令:

mvn install -pl quidem-ut/ -am -DskipTests -Pskip-static-checks
  • -pl quidem-ut/:只处理 quidem-ut 模块;
  • -am(also make):同时构建其依赖的上游模块;
  • -DskipTests:跳过测试执行;
  • -Pskip-static-checks:跳过 checkstyle 等静态检查,加快本地迭代。

CI 如何执行这些测试

README 明确指出:CI 中的执行入口是本模块中的一个标准 JUnit 测试类 QTest(QTest.java)。QTest 继承自 DruidQuidemTestBase(位于 DruidQuidemTestBase.java),并通过 getTestRoot() 把测试根目录指向:

quidem-ut/src/test/quidem/org.apache.druid.quidem.QTest

DruidQuidemTestBase 的注释清晰地描述了这套机制的工作原理(详见 DruidQuidemTestBase.java):

  1. 测试用例放在 .iq 文件中——这些文件的契约是"如果无错误地执行,其输出与自身一致";
  2. 执行器(即该基类)在单元测试运行时拾取这些文件并执行;
  3. 被测系统通过一个"看起来像 JDBC 驱动"的适配器连接(实际是 DruidAvaticaTestDriver)。

基类同时支持两个系统属性(DruidQuidemTestBase.java):

  • quidem.overwrite:覆盖模式。运行时把实际输出写到 .iq.out,再比对 .iq 与 .iq.out;若开启覆盖模式,则直接用 .out 覆盖 .iq(空值也视为 true);
  • quidem.filter:文件筛选模式,例如 *join* 只跑路径匹配的用例(自动补 .iq 后缀)。

QTest 中还有一个特殊测试 ensureNoRecordFilesPresent:断言 QuidemCaptureResource.RECORD_PATH 与测试根目录一致,且根目录中不允许残留 record-*.iq 文件(见 QTest.java)——这是防止录制产生的临时文件被误提交进测试用例目录的守护。

用 dev/quidem 脚本运行

项目还提供了一个便捷脚本 dev/quidem(见 dev/quidem),它封装了冗长的 Maven 命令,等价于执行:

mvn -Pskip-static-checks -Dsurefire.rerunFailingTestsCount=0 \
    -Dorg.slf4j.simpleLogger.log.org.apache.maven.plugin.surefire.SurefirePlugin=INFO \
    -pl quidem-ut -Dtest=QTest org.apache.maven.plugins:maven-surefire-plugin:test

支持参数:

参数 作用
-q 安静模式(脚本会追加 -Dsurefire.trimStackTrace=true)
-Dquidem.overwrite 覆盖模式,更新所有相关 .iq 文件的结果集
-Dquidem.filter=*join* 只运行路径匹配的测试(如所有含 join 的用例)

例如:

# 安静模式跑全部 QTest
dev/quidem -q

# 覆盖模式:接受所有用例的最新结果
dev/quidem -Dquidem.overwrite

# 只跑与 join 相关的用例
dev/quidem -Dquidem.filter=*join*

启动一个"测试生成 Broker":即查即录

quidem-ut 最有特色的能力是把一个 QueryComponentSupplier 包装成对外可查询的 Broker 服务。核心实现是 ExposedAsBrokerQueryComponentSupplierWrapper(见 ExposedAsBrokerQueryComponentSupplierWrapper.java),其 Javadoc 直白地写道:"A wrapper class to expose a QueryComponentSupplier as a Broker service"。

它的装配逻辑(configureGuice 方法)做了三件事:

  • 代理原始 QueryComponentSupplier 的全部能力(创建 QueryRunnerFactoryConglomerate、SpecificSegmentsQuerySegmentWalker、SqlEngine、JoinableFactoryWrapper 等);
  • 叠加一组"接近真实 Broker"的 Guice 模块(BrokerProcessingModule、QueryRunnerFactoryModule、SegmentWranglerModule、JoinableFactoryModule、BrokerServiceModule 以及 CliBroker 风格的服务绑定,见 ExposedAsBrokerQueryComponentSupplierWrapper.java),并把 Jetty 端口固定为 12345(druid.plaintextPort=12345);
  • 注册 QuidemCaptureModule,从而挂载录制用的 REST 资源。

第一步:构建项目

mvn install -pl quidem-ut/ -am -DskipTests -Pskip-static-checks

第二步:启动 Broker

mvn exec:exec -pl quidem-ut -Dquidem.record.autostart=true

quidem-ut/pom.xml 中 exec-maven-plugin 的配置(见 quidem-ut/pom.xml)会把 -Dquidem.uri 与 -Dquidem.record.autostart 透传为 JVM 系统属性,并启动主类 org.apache.druid.quidem.Launcher。启动后:

  • Broker 运行在 http://localhost:12345,提供真实 Broker 的 SQL 查询端点(/druid/v2/sql)与状态端点(/status)——这一点由冒烟测试 LauncherSmokeTest.java 验证:它先 new Launcher("druidtest:///") 并 start(),随后向 http://localhost:12345/druid/v2/sql POST {"query":"Select * from foo"} 断言返回 200,并向 /status 断言响应包含 "version":"。

Launcher(见 Launcher.java)的启动流程为:

  1. SqlTestFrameworkConfig.fromURL(uri) 解析 quidem.uri;
  2. CONFIG_STORE.getConfigurationInstance(config) 拿到对应的 SqlTestFramework(CONFIG_STORE 以 ExposedAsBrokerQueryComponentSupplierWrapper 包装每个供给器);
  3. GuiceRunnable.initLifecycle(...) 启动完整生命周期,并通过 Jetty 暴露服务;
  4. 若 quidem.record.autostart=true(系统属性 quidem.record.autostart,默认 false),自动向 http://localhost:12345/quidem/start 发起一次 HTTP GET 触发录制(对应 Launcher.java)。

第三步:选择测试后端(quidem.uri)

被包装成 Broker 的测试后端由 quidem.uri 决定,默认值为 druidtest:///。其格式为 druidtest:///?componentSupplier=<类名>,例如 README 给出的:

mvn exec:exec -pl quidem-ut -Dquidem.uri=druidtest:///?componentSupplier=ThetaSketchComponentSupplier

componentSupplier 参数指向 SqlTestFrameworkConfig.ComponentSupplier 注解所声明的 QueryComponentSupplier 实现类(详见 SqlTestFrameworkConfig.java)。这类供给器散布在核心与扩展模块的测试代码中,例如 ThetaSketchComponentSupplier 就定义在 datasketches 扩展的测试里(见 ThetaSketchSqlAggregatorTest.java,它扩展自 StandardComponentSupplier)。

这意味着:你可以在"只包含 numfoo/foo 等标准测试表的最小后端"与"注册了 datasketches、histogram 等扩展的增强后端"之间自由切换,从而针对不同功能录制 SQL 用例。

第四步:手动开始/停止录制

如果启动时没有开启 quidem.record.autostart(即省略该参数),录制不会自动开始。此时可通过 REST 手动控制:

# 开始录制(返回 QuidemRecorder 的描述信息)
curl http://localhost:12345/quidem/start

该端点由 QuidemCaptureResource.java 提供(@Path("/quidem") + @GET @Path("/start")),它通过 QuidemCaptureModule(见 QuidemCaptureModule.java)注册进 Guice。start() 的语义:

  • 若已有录制器在运行,先关闭旧的(stopIfRunning());
  • 以 quidem.uri、DruidHookDispatcher 和一个新文件 record-<时间戳>.iq 构造 QuidemRecorder;
  • 文件落在 quidem-ut/src/test/quidem/org.apache.druid.quidem.QTest 目录(RECORD_PATH,见 QuidemCaptureResource.java),文件名形如 record-1727000000000.iq。

再次调用 /quidem/start 会结束上一段录制并开启新录制;停止录制器时会通过 close() 关闭文件流并从 Hook 分发器注销。

第五步:收尾并整理用例

  • 使用完 Broker 后,工作区(即 quidem-ut/src/test/quidem/org.apache.druid.quidem.QTest/)下会生成一个新的 record-<时间戳>.iq 文件,其中包含录制期间所有被执行过的 SQL 语句;
  • 运行 dev/quidem -Dquidem.overwrite 可以更新"周边所有 .iq 文件"的结果集(覆盖模式会把 .iq.out 写回 .iq,见 DruidQuidemTestBase.java);
  • 把录制文件重命名为更具描述性的名称(例如 join-queries.iq),以便在 CI 中作为正式用例被 QTest 拾取执行。

录制与回放的底层原理

录制端:Druid SQL Hook

QuidemRecorder(见 QuidemRecorder.java)同时实现 AutoCloseable 与 DruidHook<String>。构造时:

  1. 打开 record-<ts>.iq 的 UTF-8 输出流;
  2. 写入文件头:
#started <Date>
!use druidtest:///
!set outputformat mysql
  1. 调用 hookDispatcher.register(DruidHook.SQL, this) 把自己注册为 SQL 钩子。

每当 Broker 上执行一条 SQL,DruidHookDispatcher.dispatch 就会回调 invoke(HookKey<String>, String)(见 DruidHookDispatcher.java),QuidemRecorder 随即把语句追加到文件:

# <Date>
<query>;
!ok

DruidHook 接口定义了四类钩子键(见 DruidHook.java):CONVERTED_PLAN、LOGICAL_PLAN、DRUID_PLAN(均为 RelNode)和 SQL(String),QuidemRecorder 只关心 SQL 键。

注意:录制文件里保存的是查询语句 + !ok 标记,并不包含结果集——结果集是在回放(运行 QTest/dev/quidem)时由测试后端真实计算并写入 .iq.out 的。这正是"录制骨架、回放填充期望值"的流水线。

回放端:Quidem 驱动 + DiffTestCase 比对

回放由 DruidQuidemTestBase 完成(见 DruidQuidemTestBase.java):

  1. 读取 .iq,输出写到同名 .iq.out;
  2. 用 DruidQuidemConnectionFactory(一个形如 JDBC 的适配器)连接 SqlTestFramework;
  3. Quidem.configBuilder() 装配 Reader/Writer,执行 new Quidem(config).execute();
  4. 用 Calcite 的 DiffTestCase.diff(inFile, outFile) 比对;有差异时——非覆盖模式直接 fail,覆盖模式则用 .out 覆盖 .iq。

.iq 文件的"自洽契约"(见 DruidQuidemTestBase.java)保证:只要用例文件本身没有执行错误,回放产生的输出应与文件内容一致。

动手写一个 .iq 用例

以仓库自带的示例 example.iq 为模板,一个完整的用例文件如下(为了展示结构,此处节选了其中两个语句的期望结果):

#started
!use druidtest:///
!set outputformat mysql

select * from numfoo;
+-------------------------+------+------+-----------+------+------+------+-----+-----+-----+-----+--------+--------+-----+-----+-----+--------------------+
| __time                  | dim1 | dim2 | dim3      | dim4 | dim5 | dim6 | d1  | d2  | f1  | f2  | l1     | l2     | cnt | m1  | m2  | unique_dim1        |
+-------------------------+------+------+-----------+------+------+------+-----+-----+-----+-----+--------+--------+-----+-----+-----+--------------------+
| 2000-01-01 00:00:00.000 |      | a    | ["a","b"] | a    | aa   | 1    | 1.0 |     | 1.0 |     |      7 |        |   1 | 1.0 | 1.0 | "AQAAAEAAAA=="     |
| 2000-01-02 00:00:00.000 | 10.1 |      | ["b","c"] | a    | ab   | 2    | 1.7 | 1.7 | 0.1 | 0.1 | 325323 | 325323 |   1 | 2.0 | 2.0 | "AQAAAQAAAAHNBA==" |
+-------------------------+------+------+-----------+------+------+------+-----+-----+-----+-----+--------+--------+-----+-----+-----+--------------------+
(6 rows)

!ok
select length(dim1) from numfoo;
+--------+
| EXPR$0 |
+--------+
|      0 |
|      1 |
|      1 |
|      3 |
+--------+
(6 rows)

!ok

关键点:

  • !use druidtest:/// 指定使用 druidtest 测试后端;
  • !set outputformat mysql 让结果集以 MySQL 风格表格输出(这也是录制器写入文件头的默认格式);
  • 每个查询后跟期望输出和 !ok 命令,表示"上述执行应成功";
  • 示例查询了标准测试表 numfoo(含 __time、维度列 dim1–dim6、d1/d2、浮点列 f1/f2、长整型 l1/l2、cnt 计数列、度量列 m1/m2 以及 sketch 列 unique_dim1,其值以 base64 呈现),并验证了 length(dim1) 这类标量函数。

编写新用例的推荐流程(与 DruidQuidemTestBase.java 注释一致):

  1. 在合适的目录下写一个新的 .iq 文件,只写语句和 !ok,先不写期望结果;
  2. 运行测试,框架会在旁边生成 .iq.out 文件;
  3. 把 .iq.out 复制为 .iq 以接受结果(或直接使用 dev/quidem -Dquidem.overwrite 一步到位)。

完整工作流速查

阶段 命令 / 操作
构建 mvn install -pl quidem-ut/ -am -DskipTests -Pskip-static-checks
启动录制 Broker mvn exec:exec -pl quidem-ut -Dquidem.record.autostart=true
切换测试后端 mvn exec:exec -pl quidem-ut -Dquidem.uri=druidtest:///?componentSupplier=ThetaSketchComponentSupplier
手动开始录制 curl http://localhost:12345/quidem/start
执行 SQL 触发录制 向 http://localhost:12345/druid/v2/sql 发送 JSON 查询
收尾 停止 Broker;在 quidem-ut/src/test/quidem/org.apache.druid.quidem.QTest/ 得到 record-*.iq
更新结果集 dev/quidem -Dquidem.overwrite
重命名用例 将 record-*.iq 改为描述性名称,纳入版本管理
CI 执行 标准 JUnit 测试 QTest 自动拾取全部 .iq 文件

小结与最佳实践

  • 贴近被测代码:quidem-ut 通过 ComponentSupplier 复用现有测试后端,使用例与扩展实现(如 datasketches 的 ThetaSketchComponentSupplier)放在一起,降低跨模块测试的心智负担。
  • 录制代替手写:启动 Broker 后,对真实 SQL 端点的每次查询都会被 QuidemRecorder 记录成 .iq 骨架,省去手抄 SQL 与格式化的体力活。
  • 覆盖模式要谨慎:dev/quidem -Dquidem.overwrite 会批量改写结果集,建议在确认 SQL 行为符合预期后使用,避免把回归错误"固化"进用例。
  • 勿提交录制残留:QTest.ensureNoRecordFilesPresent 会拦截 record-*.iq 残留,重命名后再提交是正道。
  • 链路可追溯:从录制(QuidemCaptureResource → QuidemRecorder → DruidHookDispatcher)到回放(DruidQuidemTestBase → Quidem → DiffTestCase.diff),再到冒烟验证(LauncherSmokeTest),整条链路均有源码可查,适合作为理解 Druid SQL 测试体系与 Hook 机制的入门样本。

如需深入,可继续阅读本仓库中的 Launcher.java、QuidemCaptureResource.java、QuidemRecorder.java、ExposedAsBrokerQueryComponentSupplierWrapper.java、DruidQuidemTestBase.java 以及 example.iq。

登录后查看全文
druid