系列导读本系列带你打通 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 会用这个默认值去调接口把返回的数据存下来。之后你在仪表板上把参数改成id2Wyn 查的是已经存好的那批数据接口根本不会被重新调用你看到的还是默认值对应的数据。参数被冻在了抽取那一刻运行时改参数完全无效。对传统的关系型数据库场景这个问题不算致命——因为抽取的数据是全量的参数过滤可以在查询层用 WHERE 条件补做。但 JSON API 场景不一样接口返回什么数据完全由 URL 参数决定抽取时拿不到的数据运行时再怎么过滤也变不出来。2.2 直连模型/直连数据集的优势直连模型和直连数据集不存储数据每次查询都实时调源。还是上面的例子选直连模型后你在仪表板上把参数改成id2Wyn 会重新发起请求接口根据新参数返回对应数据图表实时刷新。这就是我们要的参数一变数据就变的闭环。一句话结论带参数 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 多端点推荐直连模型多表关联场景直连数据集搞不定参数三层流转数据源定义 → 模型引用 → 仪表板/报表使用现在参数已经流到了模型层就差最后一步——让用户在仪表板和报表上动动手指参数就能变数据就能换。这就是本系列第三篇的内容仪表板与报表的参数联动闭环。扩展链接嵌入式分析体验