JQuick-SQL Worker 生命周期：端口、启动与关闭规范

Meta 描述：说明 jquick-sql 嵌入式 Worker 的首次启动机制、19001...19000+n 端口范围、Coordinator 生命周期以及 finally shutdown 的必要性。

标签：jquick-sql Worker、embedded、Coordinator、gRPC、Java 分布式 SQL 查询引擎、shutdown

官网示例：

FORMULAS 示例页：https://www.jquick.org/jquick-sql

github 地址：https://github.com/paohaijiao/jquick-sql

前言

嵌入式模式让 Java 服务可直接试用分布式 SQL 查询引擎，但 Worker 是真实的本地 gRPC 服务，必须管理端口与关闭流程。生命周期处理不当会导致端口被占用或测试残留资源。

首次执行时启动

JQuickSQL.embedded() 和 embedded(n) 仅标记嵌入式模式；首次 execute 时，ensureInitialized() 检查 Coordinator，必要时调用 startEmbeddedWorkers()，随后创建 Coordinator。

端口分配规则

源码将基准端口设为 19001，并按 Worker 下标递增。因而 embedded(n) 的端口范围是 19001..19000+n。例如：

java 复制代码

JQuickSQL sql = JQuickSQL.embedded(3);
try {
    sql.registerTable("flags", "enabled", true);
    sql.execute("SELECT enabled FROM flags");
} finally {
    sql.shutdown();
}

该示例在执行时会使用 19001、19002、19003；端口冲突会在 Worker 启动阶段抛出异常。

Worker 的执行职责

Worker 维护活动任务、内存分区、Worker 通道、函数管理、表达式求值和节点执行器。Coordinator 派发 Fragment 后，Worker 接收输入分区、重建物理节点、执行片段并返回结果或输出分区。

关闭流程必须放 finally

shutdown() 会关闭 Coordinator，并逐个停止本实例启动的 Worker、清空内部列表。无论查询成功、失败还是测试断言失败，都应执行：

java 复制代码

try {
    sql.execute("SELECT * FROM users").printTable();
} finally {
    sql.shutdown();
}

常见问题

**为什么 Worker 没在 embedded 时立即启动？**初始化发生在首次执行时。

**embedded(2) 的端口是什么？**19001...19002。

**shutdown 会关闭外部 Worker 吗？**门面会关闭自身 Coordinator 与其内部记录的本地 Worker；外部节点的服务治理应独立管理。

总结与拓展

严格遵守端口范围与 finally shutdown，可让嵌入式执行更适合本地开发、自动化测试和轻量级分析。生产部署还应统一规划端口与节点健康管理。

Core Advantage

Embedded workers provide a local Coordinator-Worker execution environment with explicit cleanup.

Applicable Scenarios

Local development, integration tests, batch analytics, and embedded cluster experiments.