用 Quidem 为 Apache Druid 编写 SQL 级测试:录制驱动、Broker 抓包与 .iq 用例全流程指南
用 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
说明两点:
git clone --branch quidem-record是模块开发期的示例命令,README 中标注了 FIXME;在当前仓库中,quidem-ut已作为标准 Maven 模块随项目一起构建,quidem-ut/pom.xml的父 POM 为org.apache.druid:druid:31.0.0-SNAPSHOT,直接使用本仓库即可,无需单独克隆其他分支。- 仓库当前父 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):
- 测试用例放在
.iq文件中——这些文件的契约是"如果无错误地执行,其输出与自身一致"; - 执行器(即该基类)在单元测试运行时拾取这些文件并执行;
- 被测系统通过一个"看起来像 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/sqlPOST{"query":"Select * from foo"}断言返回 200,并向/status断言响应包含"version":"。
Launcher(见 Launcher.java)的启动流程为:
SqlTestFrameworkConfig.fromURL(uri)解析quidem.uri;CONFIG_STORE.getConfigurationInstance(config)拿到对应的SqlTestFramework(CONFIG_STORE以ExposedAsBrokerQueryComponentSupplierWrapper包装每个供给器);GuiceRunnable.initLifecycle(...)启动完整生命周期,并通过 Jetty 暴露服务;- 若
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>。构造时:
- 打开
record-<ts>.iq的 UTF-8 输出流; - 写入文件头:
#started <Date>
!use druidtest:///
!set outputformat mysql
- 调用
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):
- 读取
.iq,输出写到同名.iq.out; - 用
DruidQuidemConnectionFactory(一个形如 JDBC 的适配器)连接SqlTestFramework; Quidem.configBuilder()装配Reader/Writer,执行new Quidem(config).execute();- 用 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 注释一致):
- 在合适的目录下写一个新的
.iq文件,只写语句和!ok,先不写期望结果; - 运行测试,框架会在旁边生成
.iq.out文件; - 把
.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。