JQuick-SQL JQuickTable 模型：XML 动态 SQL 的表封装边界

Meta 描述：解析项目中的 JQuickTable 模型及其 XML 动态 SQL 使用路径，并说明核心查询仍以 JQuickDataSet、JQuickRow 与 registerTable 为主。

标签：jquick-sql、JQuickTable、XML 动态 SQL、JQuickDataSet、JQuickRow、轻量级 SQL 引擎、Java 跨库查询

官网示例：

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

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

前言

项目中确实存在 com.github.paohaijiao.domain.JQuickTable：它封装 tableName、List<JQuickColumnMeta> 和 List<JQuickRow>。不过，使用它时应理解其边界：它在 runtime 的 XML 动态 SQL 路径中被传入解析工厂，再由内部逻辑调用 registerTable；核心查询入口仍是 JQuickSQL 与 JQuickDataSet。

JQuickTable 的真实结构

JQuickTable 是一个简单的表描述对象，构造器接收表名、列元数据和行记录。它没有 JDBC、CSV、NoSQL、REST 连接能力，也不会自行加载外部数据。外部数据依然需要由应用层或 jquick-connector 转换成 JQuickRow 后交给该对象或直接注册。

因此，不应将 JQuickTable 误认为完整的数据源抽象或所有场景下的稳定公共集成契约。跨版本集成时，建议优先围绕 README 中明确展示的 JQuickSQL.registerTable(...) 与 JQuickDataSet 构建代码。

XML 动态 SQL 中的使用路径

JQuickJavaXmlParseFactory 接收 List<JQuickTable>，并创建 XML 调用处理器。处理器会创建 JQuickSQL.embedded()，遍历 JQuickTable 列表，并对每个表执行 sql.registerTable(tableName, columns, rows)。

随后，XML 定义的 SQL 可通过代理接口执行，并返回 JQuickDataSet 或 List<JQuickRow>。这说明 JQuickTable 的明确用途是向 XML 代理路径提供初始表数据，而不是外部数据源连接器。

选择 JQuickTable 还是直接 registerTable

如果只是以编程方式执行 SQL，直接使用 JQuickSQL.embedded() 或 JQuickSQL.builder() 后调用 registerTable 更直观。如果项目采用 XML 动态 SQL 代理配置，并且已验证 runtime 版本的兼容性，可使用 JQuickTable 组织传入表。

无论选择哪种方式，表结构、行数据、类型映射和数据刷新都由应用层负责。Java 分布式 SQL 查询引擎只对已注册数据集进行规划与执行。

代码案例

java 复制代码

import com.github.paohaijiao.domain.JQuickTable;
import com.github.paohaijiao.engine.JQuickSQL;
import com.github.paohaijiao.statement.JQuickColumnMeta;
import com.github.paohaijiao.statement.JQuickDataSet;
import com.github.paohaijiao.statement.JQuickRow;
import java.util.Arrays;
import java.util.List;

public class JQuickTableModelDemo {
    public static void main(String[] args) {
        List<JQuickColumnMeta> columns = Arrays.asList(
            new JQuickColumnMeta("id", Integer.class, "users"),
            new JQuickColumnMeta("name", String.class, "users")
        );
        List<JQuickRow> rows = Arrays.asList(
            row("id", 1, "name", "Alice"),
            row("id", 2, "name", "Bob")
        );

        // JQuickTable 可用于 runtime 的 XML 动态 SQL 传参场景。
        JQuickTable table = new JQuickTable("users", columns, rows);

        // 常规编程查询仍建议采用明确的 registerTable 主路径。
        JQuickSQL sql = JQuickSQL.embedded();
        try {
            sql.registerTable(table.getTableName(), table.getColumns(), table.getRows());
            JQuickDataSet result = sql.execute("SELECT id, name FROM users ORDER BY id");
            result.printTable();
        } finally {
            sql.shutdown();
        }
    }

    private static JQuickRow row(Object... values) {
        JQuickRow row = new JQuickRow();
        for (int i = 0; i < values.length; i += 2) row.put((String) values[i], values[i + 1]);
        return row;
    }
}

常见问题

**JQuickTable 是外部数据源连接器吗？**不是。它只包含表名、列和行，不提供外部连接能力。

**是否必须使用 JQuickTable？**不必须。核心 API 可直接使用 registerTable 注册 JQuickDataSet 或列与行。

**它是否适合长期对外 SDK 契约？**需谨慎。它存在于当前 runtime/XML 路径，但核心、通用的查询模型仍应以 JQuickDataSet、JQuickRow 和 registerTable 为中心。

总结与拓展

JQuickTable 的价值在于为 XML 动态 SQL 代理传递表数据，而非建立数据源连接层。理解这一定位，可以避免把内部模型扩展成不存在的 connector API，并使 jquick-sql 的表注册、查询与动态 SQL 使用方式保持清晰。

Core Advantage

Offers a compact table container for the XML dynamic-SQL path while preserving registerTable as the core execution boundary.

Applicable Scenarios

XML-backed query proxies, small embedded query modules, and applications that already prepare rows and metadata in Java.