ToolJet 3.0 云升级迁移指南:破坏性变更清单、变量访问新规则与 metadata 机制解析

ToolJet 3.0 云升级迁移指南:破坏性变更清单、变量访问新规则与 metadata 机制解析

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

ToolJet Cloud 于 2024 年 11 月 11 日自动升级至 3.0 版本,本次升级包含多项破坏性变更:动态组件引用被移除、组件/查询 ID 映射拆分、废弃组件与本地数据源下线,以及 REST API 响应头访问方式重构。本文基于仓库中的 v3.0.0-LTS 云迁移文档,逐项说明每类破坏性变更的具体影响、迁移操作与代码示例,并结合服务端源码印证metadata机制的真实实现,帮助你在升级前完成应用改造,确保升级后所有应用、查询与工作流继续正常工作。

升级背景:为什么必须提前改造

ToolJet Cloud 的 3.0 升级由平台自动执行,无法推迟或暂停,因此所有变更必须在 11 月 11 日之前完成。升级当日,任何仍使用已移除特性(尤其是旧版 Kanban Board 组件)的应用将直接崩溃且不可用。

迁移工作的优先级排序建议如下:

动态输入限制:禁止动态构造组件名引用

3.0 版本中,不能再通过变量或表达式动态拼接组件名来引用组件。这类写法在旧版本中依赖全局可解析的组件命名空间,而 3.0 的前端引擎不再支持这种动态路径解析。

以下三种模式在 3.0 中均不再受支持:

1. 用变量构造组件名:

// 升级后不再工作 {{components[variables.componentNameVariable].value}}

2. 动态引用组件(用其他组件的状态拼接组件 ID):

// 不受支持 {{components['textinput' + components.tabs1.currentTab].value}}

3. 动态访问嵌套属性:

// 不允许的动态属性访问 {{components.table1[components.textinput1.value]}}

替代方案是全部改为静态引用:

{{components.textinput1.value}} {{components.table1.selectedRow}} {{queries.query1.data}}

迁移操作清单:

• 全局检索应用中所有动态组件名引用(可搜索components[这类方括号动态索引模式)并重构;
• 将所有动态组件引用替换为静态引用;若原逻辑需要"按当前 Tab 切换取不同组件的值",可改为在事件处理逻辑中做分支判断,而不是在表达式里动态拼 ID;
• 改造完成后测试所有组件交互,确认事件链路与数据绑定未受影响。

组件与查询同名:升级期间的临时冲突

::: 仅升级期间的问题 一旦应用运行在 ToolJet 3.0 之上,组件与查询使用完全相同的名称不会有任何问题,此约束只存在于升级过程本身。 :::

原因在于历史实现:旧版本对组件和查询共用同一个全局 ID 到名称的映射表(ID-to-name map),而 3.0 将这两张映射表拆分开了。升级时,如果某个组件正在引用一个与它同名的查询,映射在拆分过程中可能断裂。

典型场景:一个名为userData的表格组件绑定了同样名为userData的查询。升级后该绑定可能失效,表格查不到数据。

应对步骤:

1. 审查应用中所有组件与查询同名(名字完全一致)的情况;
2. 临时重命名其中一方(建议重命名查询),保证升级期间名称唯一;
3. 记录所有被重命名的组件/查询,形成文档,供升级完成后按需要回滚;
4. 重命名后测试受影响的组件和查询。

属性面板逻辑:变量存在性检查的新规则

3.0 对属性面板中表达式访问变量、组件、查询的方式做了收敛,核心规则是:关键字之后必须紧跟足够数量的属性键,不允许悬空的命名空间引用,也禁止使用in、Object.keys、hasOwnProperty这类"探测式"写法判断变量是否存在。

新的变量访问规则

• 对components、queries、page.variables关键字,其后至少要有两个键,例如components.textinput1.value(textinput1与value两个键);
• 对variables关键字,其后至少要有键数大于一,即必须至少带一个键,例如variables.name。

受支持的标准写法:

// 受支持的格式 components.textinput1.value components?.textinput1?.value components["textinput1"].value queries.restapi1.data page.variables.name variables["name"] variables.name

不再受支持的存在性判断写法:

// 升级后不再受支持 {{'name' in variables}} {{Object.keys(variables).includes('name')}} {{variables.hasOwnProperty('name')}}

官方推荐的变量存在性检查方式是使用空值合并运算符:

// 推荐的变量存在性检查 {{variables['name'] ?? false}}

迁移操作清单:

• 审查所有属性面板中的变量检查逻辑;
• 将in/Object.keys(...).includes(...)/hasOwnProperty(...)写法替换为??空值合并模式;
• 删除所有不符合"最少键数"要求的悬空引用;
• 更新后对所有使用了变量检查的组件做回归测试。

需要注意:这些变更会改变应用与变量、组件的交互方式,测试必须覆盖"变量已定义"与"变量未定义"两种分支,确认条件渲染、默认值兜底等行为符合预期。

多页应用:跨页同名组件的查询绑定限制

当前版本存在一个明确的限制:当同一个组件名出现在多个页面并绑定查询时,查询只在组件最初被关联的那个页面上正常工作。

复现场景:

1. 应用有page1和page2,两个页面各有一个名为textinput1的组件;
2. 你在page1中创建一个查询,并绑定textinput1;
3. 查询只在page1上正确工作;
4. 切换到page2后,即使页面里存在同名组件,查询也不会按预期取到该页面的输入值。

应对策略(二选一):

• 重命名组件,保证所有页面之间组件名唯一;
• 或者修改查询,改为通过 query 参数(查询选项参数)显式传值,而不是依赖组件直接绑定。

同时做好文档记录(哪些组件被重命名、查询参数如何调整)并测试受影响页面及其交互。官方在后续版本中计划引入跨页面强制组件名唯一的校验功能,在此之前,多页应用应一律采用全应用范围内唯一的组件命名规范。

废弃功能移除

旧版 Kanban Board 组件彻底下线

旧版已废弃的Kanban Board组件在升级后将完全停止工作,仍在使用它的应用会在升级后崩溃。必须迁移到新版Kanban组件,操作顺序为:

1. 立即排查应用中所有旧版 Kanban Board 组件实例;
2. 用新版 Kanban 组件重建看板;
3. 将数据与配置(列定义、卡片映射等)迁移到新组件;
4. 删除旧 Kanban Board 组件;
5. 更新所有连到旧看板的查询与工作流;
6. 全面测试,确认原有功能(拖拽、卡片事件等)完整保留。

本地数据源:迁移到全局工作区数据源

本地(Local)数据源在 3.0 中被移除。如果你没有在升级前完成迁移,升级后会收到"本地数据源不再受支持"的错误提示。

迁移操作:

• 识别应用中所有本地数据源;
• 将其迁移为全局工作区(global workspace)数据源;
• 更新所有引用这些数据源的查询与组件;
• 迁移后测试所有受影响的组件和查询。

详细的迁移步骤参见仓库中的 本地数据源迁移指南。

Workspace Variables:替换为 Workspace Constants

旧的 Workspace Variables 需要替换为Workspace Constants,操作要点:

• 找出所有 Workspace Variables 的使用点;
• 替换为 Workspace Constants;
• 更新使用这些变量的所有组件与查询;
• 为新的常量配置基于角色的访问权限;
• 迁移后测试全部受影响功能。

安全模型上的差异值得注意:Workspace Constants 被设计为仅在服务端解析,不会暴露到客户端,安全性更高;并且可以为常量配置角色的增(create)、改(update)、删(delete)权限,实现细粒度的访问控制。

详细的迁移步骤参见仓库中的 Workspace Variables 迁移指南。

响应头访问重构:responseHeaders 迁移到 metadata

3.0 为所有数据源类型引入了统一的 metadata 能力,暴露关于请求与响应的附加信息——此前只有 REST API 与 GraphQL 数据源具备这一能力。访问方式也随之变化:

// 旧方式:仅 REST API / GraphQL 可用,3.0 起不再推荐 {{queries.<queryName>.responseHeaders}}

// 新方式:所有数据源通用 {{queries.<queryName>.metadata}}

metadata对象包含本次请求与响应的详细信息:请求 URL、请求方法、请求头、请求参数、响应状态码、响应头。更多字段说明可参考 metadata 与 cookies 文档。

源码印证:metadata 是如何生成的

从服务端源码看,metadata 的注入发生在查询执行返回结果之前。在 查询执行工具服务 中,每次查询成功后都会将状态服务产生的响应元数据合并进结果对象:

result['metadata'] = { ...(result['metadata'] || {}), ...queryStatus.getResponseMetadata(), }; if (dataSource.kind === 'restapi' || dataSource.kind === 'grpcv2') { const queryDefinition = dataSource.kind === 'restapi' ? (result as any)['metadata']?.['request']?.['url'] : dataQuery.options?.['raw_message']; (result as any)['metadata']['queryDefinition'] = queryDefinition; }

其中时间维度的字段来自 DataQueryStatus 状态服务:

getResponseMetadata() { return { queryRunTimeMs: this._duration, finished: this._startTime + (this._duration ?? 0), requestSentTimestamp: this._startTime, }; }

由此可以确认:

• 前端拿到的metadata由两部分合并而成:数据源插件自身返回的请求/响应信息(如 REST API 的 request URL、method、headers、params 与响应状态码、响应头),加上 ToolJet 附加的查询运行耗时(queryRunTimeMs)、请求发送时间戳与完成时间戳;
• 对restapi与grpcv2数据源,服务端还会额外写入queryDefinition字段,分别取请求 URL 或 gRPC 的原始消息体,便于前端在响应面板中展示本次执行的定义;
• 从源码结构看,同一套状态服务还负责把含appId、appName、dataSourceType的 enriched metadata 写入审计日志上下文,即 metadata 不仅服务于前端表达式,也支撑了审计与可观测性链路。

迁移操作:

• 检索应用中所有responseHeaders访问点;
• 统一替换为metadata取值(原先直接取头部的场景,现从metadata中对应位置取响应头);
• 测试所有受影响的查询与组件。

升级前完整自检清单

按文档要求,以下事项须在升级日(11 月 11 日)前全部完成:

1. 动态引用:搜索components[动态索引、components[变量]、组件ID + 字符串拼接等模式,全部改为静态引用,并回归测试组件交互;
2. 同名冲突:列出组件/查询同名清单,临时重命名并记录,升级后按需回滚;
3. 变量检查:将in variables、Object.keys(variables).includes(...)、variables.hasOwnProperty(...)全部改写为variables['name'] ?? false形式,并确认components/queries/page引用均满足最少键数要求;
4. 多页同名组件:跨页面组件重命名为全局唯一,或改用查询参数传值;
5. Kanban Board:完成旧组件到新 Kanban 组件的迁移与数据搬迁,删除旧组件并更新关联查询/工作流;
6. 本地数据源:全部迁移为全局工作区数据源,更新引用;
7. Workspace Variables:全部替换为 Workspace Constants,并配置角色级访问权限;
8. 响应头:所有responseHeaders访问切换为metadata,并对涉及 REST API 的应用验证请求 URL、方法、状态码等字段的可用性。

所有改动完成后,在测试环境完整走一遍关键业务流程。由于升级自动执行且不可回退,只有完成上述清单,才能保证应用平滑运行在 ToolJet 3.0 之上。

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet