虚拟数据源

和JDBC数据源类似，也支持如下的三种数据源类型：

• JDBC连接数据源
• JNDI连接数据源
• CUSTOM数据源：自定义数据源,利用自定义类返回java.sql.DataSource

但是和JDBC数据源有差别的是，当你定义好数据源后，还无法在报表或数据流程中直接使用它。

你还需要继续在虚拟数据源下添加好数据集，定义好的数据集才可以在报表或数据流程中使用。

数据集合的类型有：

• 表格
• 视图
• SQL

你可以单击虚拟数据源，进入管理界面后单击添加按钮，看到数据集添加下拉菜单：

添加表格或视图

如果是添加表格或视图，则下拉列表中会自动出现对应的表格或视图供开发人员选择，选中后命名这个数据集的名字就可以。

一般来说同名表格在该处添加一个即可。不要重复。

添加SQL数据集

开发人员也可以自定义sql定义数据集：

对于SQL类型的Dataset，对于SQL的定义也支持表达式的形式定义动态SQL,包括对查询参数也是支持的。只是最终参数的定义是在报表或数据流程那边。运行时如果是报表引用统一数据源中的SQL数据集，则参数由报表那边负责定义和初始化，执行时系统会自动传入Sql数据集，并动态解析参数查询数据。

虚拟数据源的安全性

你在数据流程，报表，仪表盘设计时，只能引用虚拟数据源中预先定义好的数据集，供系统进行设计和开发。但是不能在设计时加入新的表或视图，或SQL查询别的数据。 这样有利于对数据源的数据进行控制，只开放系统设计需要的数据。从而提高数据安全性。

为什么使用虚拟数据源

虚拟数据源相比直连数据库数据源具有以下核心优势：

1. 数据安全管控

使用直连 JDBC 数据源时，报表开发人员可以在 SQL 中自由访问数据库中的任何表、视图或存储过程，存在数据泄露风险。而虚拟数据源通过白名单机制彻底解决这一问题：

• 管理员在 BaskServer 中仅开放业务系统确实需要的数据集
• 报表开发人员在设计时只能从预定义列表中选择，无法越权访问其他数据
• 即便开发人员熟悉底层数据库结构，也无法在报表中直接构造任意 SQL 查询敏感数据

典型场景：财务报表开发人员可以使用"月度销售汇总"数据集，但无法通过报表访问"员工薪资"等敏感表。

2. 数据定义集中管理、一处修改全局生效

直连数据集的 SQL 分散在每一张报表内部，当业务逻辑或表结构发生变化时，需要逐一修改所有相关报表，维护成本极高。虚拟数据源将数据定义统一托管在 BaskServer 中：

• 一处定义，多处复用：同一个虚拟数据集可以被报表、仪表盘、数据流程等多个产品同时引用
• 一处修改，全局生效：当 SQL 逻辑需要调整时，只需在 BaskServer 中修改一次，所有引用该数据集的报表自动获得更新

典型场景：20 张报表共用同一个"订单明细"数据集，当订单表新增字段时，只需在 BaskServer 中更新一次数据集定义即可。

3. 职责分离，团队协作更高效

虚拟数据源使数据层与展示层的开发职责得到清晰分离：

4. 跨产品数据一致性

同一个虚拟数据源下的数据集可以同时用于：

• BaskReport 报表设计
• BaskReport 仪表盘 图表配置
• BaskAdapt 数据流程

各端引用同一数据源，确保不同产品之间的数据口径完全一致。

与报表结合的完整流程

流程概览

① 管理员在 BaskServer 定义虚拟数据源及虚拟数据集（含 SQL 参数定义）
        ↓
② 报表开发人员添加服务器数据源（选择虚拟数据源）
        ↓
③ 从虚拟数据集列表中选择并添加数据集
        ↓
④ 在报表端定义与 SQL 中对应的查询参数
        ↓
⑤ 将数据集字段绑定到报表单元格
        ↓
⑥ 配置查询表单（可选），实现交互式数据过滤
        ↓
⑦ 保存并预览报表

步骤详解

① 在 BaskServer 定义虚拟数据集（管理员）

在 BaskServer 平台中配置好虚拟数据源，并添加所需的 SQL 数据集。SQL 中可预留参数占位（如 ${$dept_id}），但参数的初始化由报表端负责。

② 报表端添加服务器数据源

报表设计器 → 数据源设置面板 → 添加 → 选择添加服务器数据源 → 选中对应的虚拟数据源。

③ 添加虚拟数据集

数据集标签页 → 添加 → 选择服务器虚拟数据源数据集 → 双击列表中的目标数据集 → 确定。

④ 定义报表参数

报表设置 → 参数配置，按照 SQL 中使用的参数名逐一添加。参数名须与 SQL 表达式中的 $paramName 对应。

示例：SQL 中使用了 $dept_id 和 $start_date，则需在报表端定义同名参数：

⑤ 绑定数据集字段

在单元格属性中输入绑定表达式：

数据集名称.聚合方式(字段名)

例如：

employees.list(emp_name)
employees.list(salary)
employees.sum(salary)

⑥ 配置查询表单（可选）

点击报表设计器上方的查询表单标签页，将已定义的参数组件拖入工作区，配置好标签、默认值及提交行为，即可实现交互式数据查询。

详见：参数实现数据查询

调试与排查

查看运行时 SQL

虚拟数据集 SQL 类型数据集中的动态 SQL 在运行时执行，若需查看实际执行的 SQL，可开启日志输出。

SpringBoot 项目（在 application.yml 中配置）：

logging:
  level:
    com:
      basksoft:
        core:
          database: DEBUG

快速开关（v2.0.2+）：

baskreport.sql.output.enable=true

开启后，运行时 SQL 及动态查询参数将直接输出到控制台，便于快速定位问题。

常见问题

与其他数据源类型对比