系列导读：本系列带你打通 JSON API 带参数数据源的全链路——从数据接入、数据准备，到仪表板/报表的参数联动。
- 第1篇（接入篇）：配置带参数的 JSON API 数据源
- 第2篇（准备篇）：直连模型选型，参数为什么不生效？
- 第3篇（联动篇）：仪表板筛选器+报表查询面板，参数联动全闭环
参数配好了，为什么不生效？
上一篇我们配好了一个带参数的 JSON 数据源：基址jsonplaceholder.typicode.com，三个端点 posts/users/albums，一个基址参数id。
但很多人到这一步会踩一个坑——数据源配好了，参数也定义了，结果做出来的仪表板改参数却没反应，数据纹丝不动。
问题出在哪？出在数据准备层的选择上。
Wyn 在数据准备阶段提供了多种方案：数据模型有直连模型和抽取模型，数据集有直连数据集和缓存数据集。这四种方案对参数的支持完全不同——选错了，参数在运行时就失效，接口根本不会被重新调用。
本篇带你完成四件事：
- 带参数的 JSON API 数据源，必须选直连模型和直连数据集，没有商量
- 抽取模型/缓存数据集会让参数在抽取/缓存时被固化，运行时改参数不生效
- JSON API 多端点天然多表，推荐用直连模型而非直连数据集
- 参数生命周期是三层流转：数据源定义 → 模型/数据集引用 → 仪表板/报表使用
一、数据准备方案概览：8种里只有2种支持参数
先看全貌。Wyn 的数据准备方案分三大类，共8种：
这张表是本篇的核心。看不懂没关系，下面逐个解释。
1.1 数据模型：直连模型 vs 抽取模型
数据模型是 Wyn 进行可视化建模的载体，支持跨源关联、业务字段定义、权限控制等。
- 直连模型：仅包含对相关运算过程的定义，实际数据在浏览报表/仪表板时会实时计算、获取。换句话说，模型里存的是"怎么查"，不是"查到的数据"。每次查询都实时调源，展示的数据是实时刷新的。
- 抽取模型：把数据从源端抽取出来，存储到 Wyn 内部。查询时查的是 Wyn 里的存储，不再调源。数据靠定时任务或手动刷新来更新。
1.2 数据集：直连数据集 vs 缓存数据集
数据集偏轻量，适合单表或简单查询场景。
- 直连数据集：和直连模型同理，实时查询，数据实时刷新。
- 缓存数据集：将按定义运算得出的数据存于 Cache 缓存中，然后再用于创建仪表板。缓存数据集创建完成后可以配置定时任务或手工刷新缓存数据。
此外 Wyn 还提供原生查询数据集、流式数据集、推送数据集等方案，分别适用于特定数据库原生语法查询、外部数据实时推送等场景，但这些方案不涉及本文讨论的参数流转机制，此处不展开。
二、为什么带参数的 JSON API 必须直连？抽取模型让参数"冻"住
这是本篇最重要的结论，单独拎出来讲。
2.1 抽取模型/缓存数据集的致命问题
抽取模型和缓存数据集的本质是"提前把数据搬过来存着"。这个"搬"的动作发生在抽取/缓存时，而参数也是在那一刻被代入的。
这意味着什么？
假设你在基址定义了id参数，默认值是1,2。如果你选了抽取模型，Wyn 会用这个默认值去调接口，把返回的数据存下来。之后你在仪表板上把参数改成id=2，Wyn 查的是已经存好的那批数据，接口根本不会被重新调用，你看到的还是默认值对应的数据。
参数被"冻"在了抽取那一刻，运行时改参数完全无效。
对传统的关系型数据库场景，这个问题不算致命——因为抽取的数据是全量的，参数过滤可以在查询层用 WHERE 条件补做。但 JSON API 场景不一样，接口返回什么数据完全由 URL 参数决定，抽取时拿不到的数据，运行时再怎么过滤也变不出来。
2.2 直连模型/直连数据集的优势
直连模型和直连数据集不存储数据，每次查询都实时调源。
还是上面的例子，选直连模型后，你在仪表板上把参数改成id=2，Wyn 会重新发起请求：
接口根据新参数返回对应数据，图表实时刷新。这就是我们要的"参数一变，数据就变"的闭环。
一句话结论：带参数 JSON API = 直连模型 + 直连数据集，没得选。这是参数能实时生效的前提。
三、直连模型 vs 直连数据集，怎么选
确定了"直连"之后，还要在直连模型和直连数据集之间二选一。
JSON API 场景有一个天然特点：一个数据源往往有多个端点，每个端点是一张表。比如上一篇配的 posts、users、albums 三张表，要做"用户及其文章、相册"的关联分析，就得跨表 JOIN。这种场景直连数据集搞不定，得用直连模型。
所以本系列后续示例统一用直连模型。
当然，如果你的接口只有一个端点、单表直查就够了，直连数据集更轻量，按需选择。
四、实操：基于直连模型引用参数
4.1 新建直连模型
在 Wyn 中新建数据模型，数据源选择上一篇配好的 JSON 数据源。模型类型务必选直连模型，不要选成抽取模型。
4.2 选择数据源并勾选表
进入数据源选择界面，选择上一篇配置好的数据源，并勾选 posts、users和albums 三个表和对应的列。
4.3 建立表关联关系
根据业务关系建立关联。例如 users 和 posts 通过id和userId关联，users 和 albums 通过id和userId关联。拖拽表即可建立关联关系。
4.4 预览验证参数生效
下图以users为例。
- 模式设计器中，选中对应的表，点击预览按钮，在弹窗中确认参数id 的默认值为1,2；确认后，数据预览只显示id 为1和2的用户，这说明参数已经从数据源"流"到了模型层。
4.5 保存并预览模型数据
保存直连模型并预览模型数据：
到这里，参数已经"流"到了模型层，等待被仪表板和报表使用。
五、参数机制详解
这一节系统讲清参数的机制，这也是本篇的重点之一。
5.1 参数的生命周期：三层流转
参数不是定义完就完了，它要经历三层流转才能发挥作用：
- 第一层：在 JSON 数据源的定义界面配置参数，这是参数的"源头"。上一篇做的就是这个。
- 第二层：数据模型引用数据源时，参数自动透传到模型层/数据集层。直连模型/直连数据集每次查询都会把当前参数值下推给接口。
- 第三层：仪表板通过仪表板参数（筛选器）、报表通过报表参数（查询面板），把用户的操作转化成参数值，再下推到模型，最终触发接口调用。
三层流转通了，"改参数→换数据"的闭环才成立。下一篇专门讲第三层。
5.2 参数的四个属性
每个参数有四个关键属性，配置时要一次想清楚：
这四个属性要和后端接口的约定保持一致。
5.3 参数的作用域：基准地址参数 vs 端点地址参数
这是最容易混淆的点，再强调一次：
- 基准地址参数：定义在基址地址下，是公共参数，所有引用该基址的端点都能使用。适合多租户 ID 这类全局过滤条件。
- 端点地址参数：定义在某个具体端点上，只对当前端点生效。适合某个接口独有的过滤条件，比如 Posts 端点特有的
userId过滤。
作用域配错了，要么参数不生效，要么过滤范围不符合预期。
5.4 参数下推时机：直连模型的实时性
直连模型下，参数的下推时机是每次查询。也就是说，仪表板每次刷新、用户每次改筛选器，都会带着当前参数值重新调用接口。
这带来一个性能考量：如果接口响应慢，参数频繁变更会导致明显的卡顿。所以选直连模型时，要确保后端接口的性能能扛住实时查询。如果接口本身很慢，可以考虑在后端做缓存，而不是在 Wyn 这层用缓存数据集——因为后者会让参数失效。
六、避坑指南
- 别误选抽取模型/缓存数据集
这是最常见的坑。新建模型时默认可能不是直连，一定要确认模型类型选的是"直连模型"。选错了，参数运行时不生效，排查起来很费时间。
- 参数数据类型和多值分隔符要和数据源保持一致
模型层引用的是数据源定义的参数，属性必须一致。如果数据源里 id 是字符串多值逗号分隔，模型层不能改成分号分隔，否则拼接出的 URL 不对。
- 直连模型下参数变更触发接口调用，注意接口性能
直连的优势是实时，代价是每次查询都调接口。如果接口 QPS 承载有限，或者响应较慢，要做好后端侧的优化。
- 跨源建模时 JSON 参数无法下推到关系型数据源
如果你在直连模型里同时关联了 JSON 数据源和关系型数据库，JSON 数据源的参数只对 JSON 端点生效，不会下推到关系型数据库的查询里。关系型数据源的过滤要用它自己的 WHERE 条件。
七、本篇小结
本篇是全链路的"中段"，把参数从数据源接到了数据准备层。
回顾三个核心结论：
- 带参数 JSON API 必须选直连：抽取模型/缓存数据集会让参数固化，运行时失效
- JSON API 多端点推荐直连模型：多表关联场景直连数据集搞不定
- 参数三层流转：数据源定义 → 模型引用 → 仪表板/报表使用
现在参数已经"流"到了模型层，就差最后一步——让用户在仪表板和报表上动动手指，参数就能变，数据就能换。
这就是本系列第三篇的内容：仪表板与报表的参数联动闭环。
扩展链接
嵌入式分析体验
