ToolJet 工作流 Response 节点配置指南：用 JavaScript 定制工作流返回结果

ToolJet 工作流 Response 节点配置指南：用 JavaScript 定制工作流返回结果

【免费下载链接】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 的可视化工作流中，Response 节点是决定"最终返回什么"的出口：你可以通过一段 JavaScript 代码，把工作流中任意节点的数据——无论是单条记录、完整数据集还是加工后的 CSV——组合成结构化的响应对象。本文以官方文档 results.md 为核心，结合仓库中的工作流执行引擎源码，系统讲解单节点返回、多节点返回、JavaScript 数据精调，以及工作流在 Webhook 触发与 ToolJet 应用内触发两种场景下的结果返回行为。读完本文，你将能独立配置出返回任意结构、任意子集数据的 Response 节点，并理解其结果在 API 层是如何被组装与交付的。

什么是 Response 节点

Response 节点是工作流画布中的终端节点，负责定义整个工作流对外输出的数据形状。它的配置界面本质上是一个 JavaScript 代码编辑器——你写入的表达式会按代码语义求值，并把结果作为工作流的最终响应返回。

从源码视角看，Response 节点在整个执行引擎中承担着"收尾写响应"的职责。仓库中 server/src/modules/workflows/AGENTS.md 明确将其描述为：

Response Node— terminal node that writes the HTTP response for webhook-triggered runs (custom status code, may be fx-evaluated)；由执行服务中的processResponseNode+buildResponseNodeMetadata负责处理。

也就是说，当工作流通过 Webhook 触发时，Response 节点不仅要产出数据，还要参与 HTTP 响应的构建（包括自定义状态码）。执行服务接口 IWorkflowExecutionsService.ts 中定义的ResponseNodeMetadata印证了这一点：

export interface ResponseNodeMetadata { status: 'ok' | 'failed'; request?: Record<string, unknown>; response: { statusCode?: number; headers?: { 'X-Workflow-Response-Status-Set': boolean; }; }; }

status标识执行成败，response.statusCode允许自定义 HTTP 状态码，X-Workflow-Response-Status-Set头则标记"状态码是否由 Response 节点显式设定"——这些都是理解工作流 API 响应行为的关键细节。

此外，文档明确指出每个工作流可以有多个 Response 节点。你可以依据不同的分支路径（如 If 条件节点后的成功/失败分支）配置多个出口，每个出口返回各自适合的结果结构。

上图展示了 Response 节点的典型配置场景：画布左侧是getStudentsData→calPercentage→sendMarksheet→If condition的链路，右侧的 Response 节点面板中，核心的Response object编辑区填写了return ({ output: "success" })，即返回一个包含output字段的对象。

从单个节点返回数据

最常见的使用方式是：把工作流中某个节点（通常是经过 JavaScript 运算的最终数据处理节点）的整体输出直接作为响应。

考虑这样一个场景：一个工作流通过getSalesData节点获取销售数据、通过getInventory节点获取库存数据，再由generateCSVData节点用 JavaScript 运算把两者合并生成 CSV 文件。此时只需要在 Response 节点中写：

return ({generateCSVData})

({generateCSVData})是 JavaScript 的对象简写语法，等价于{ generateCSVData: generateCSVData }——它把generateCSVData节点返回的完整数据对象作为响应的generateCSVData字段返回。

这条返回语句会在执行引擎的 JavaScript 沙箱中求值。根据 AGENTS.md，工作流执行以 BullMQ 作业的形式运行在isolated-vm的 JS 沙箱中，节点逐个执行并持久化每个节点的执行结果（WorkflowExecutionNode中保存每个节点的result与state）。Response 节点正是读取这些已落盘的上游节点结果，再通过return语句将它们组合输出。

从多个节点返回数据

Response 节点同样可以自由引用其他任意节点的数据，有两种做法：

1. 返回完整数据集：直接把节点整体放入返回对象；
2. 只返回所需部分：通过.data等属性访问节点输出中的特定字段。

官方文档给出的多节点示例：

return ({sales: getSalesData.data, inventory: getInventory.data, csv: generateCSVData.data})

注意这里与"单节点返回"的差异：单节点示例直接返回generateCSVData这个节点对象，而多节点示例显式访问了.data属性。这是因为当返回对象由多个字段组成时，你通常关心的是各节点实际产生的数据（.data），而非包含元数据的节点包装对象。实践上建议统一使用.data访问，让响应结构更干净、可预测。

这种写法把三个数据源组合成一个平铺的对象：sales、inventory、csv，下游消费方（API 调用者或 ToolJet 应用内的查询）可以按字段名直接取值。

用 JavaScript 精调返回数据

Response 节点的返回表达式不限于"原样透传"，你可以对数据执行任意 JavaScript 操作，例如数组方法、映射、过滤、排序等。文档以slice为例，只取每个数据集的前 5 条记录：

return ({sales: getSalesData.data.slice(0,5), inventory: getInventory.data.slice(0,5), csv: generateCSVData.data})

这就实现了"只把数据子集暴露给外部"的典型需求——例如接口只需要最近 5 笔销售记录用于预览看板，而不希望把全量数据带出工作流。

在此基础上可以组合更丰富的变换，例如：

return ({topProducts: getSalesData.data .sort((a, b) => b.revenue - a.revenue) .slice(0, 10) .map((item) => ({ name: item.product, revenue: item.revenue })), inventorySummary: { total: getInventory.data.length, lowStock: getInventory.data.filter((item) => item.stock < 10) }})

需要注意：文档示例中的return与对象之间跨行书写是合法的 JS 语法（return后换行再跟括号表达式），但为了可读性和规避 ASI（自动分号插入）陷阱，更推荐将return与(保持在同一行，即return ({ ... })的写法。配置面板本身是一段 JavaScript 求值环境，表达式遵循标准 ES 语法，你还可以引用fx求值相关的上下文变量（Response 节点支持 fx-evaluated，见 AGENTS.md），实现动态化响应。

工作流执行：结果如何被返回

Response 节点配置完成后，其返回数据会在工作流执行的两种典型触发方式下，以不同形态交付：

通过 Webhook / API 触发时

当工作流通过外部触发器（Webhook）执行时，Response 节点中配置的数据会包含在 API 响应中直接返回给调用方。从 workflow-executions.controller.ts 可以看到，执行接口POST /workflow_executions的返回类型被定义为：

Promise<{ workflowExecution: WorkflowExecution; result: any }>

其中result即工作流最终产出——也就是 Response 节点return的对象。类似地，从 ToolJet 应用内触发的执行接口POST :id/trigger（见 workflow-executions.controller.ts）返回：

Promise<{ result: any }>

这也对应了文档的说明：当工作流在 ToolJet 应用内被触发时，返回的数据会以与常规查询（query）完全相同的格式交付——也就是说，你在应用构建器中运行一个工作流查询，得到的data就是 Response 节点定义的结构，可以直接绑定到组件或用于后续 JS 处理，无需额外解析。

关于响应状态码

由于 Response 节点承担 HTTP 响应写入职责，你还可以借助自定义状态码区分业务结果。ResponseNodeMetadata.response.statusCode字段与X-Workflow-Response-Status-Set头（见 IWorkflowExecutionsService.ts）表明：当 Response 节点显式设置了状态码时，执行引擎会标记该头，调用方据此判断状态码是否为工作流自定义。这一机制让"业务失败也返回 200、业务成功返回 200"或反向定制成为可能，适合对接外部系统的复杂契约。

执行状态与实时反馈

需要补充的是，Response 节点只是结果的出口，一次完整执行的生命周期由执行引擎全程跟踪：工作流执行状态在triggered/running/completed/error/terminated之间流转（见 AGENTS.md），并通过 SSE 流式推送给前端。你可以通过GET /workflow_executions/:id/status查询单次执行的节点明细——每个节点（含 Response 节点）都会记录executed布尔值与result结果（见 IWorkflowExecutionsService.ts），用于排查"返回的数据是否符合预期"。

配置要点与最佳实践

综合文档与源码，整理出以下实操要点：

1. 多出口设计：一个工作流可配置多个 Response 节点，适合按分支（成功/失败/不同条件路径）返回差异化结构。配合 If 条件节点，可以让错误分支返回带error字段的对象，成功分支返回业务数据。
2. 善用.data访问节点输出：多节点组合返回时显式使用getSalesData.data这类属性访问，避免把节点的内部包装结构泄露给调用方。
3. 返回表达式是完整 JS 上下文：slice、sort、map、filter等标准数组方法均可使用，可在 Response 节点内完成字段裁剪、重命名、聚合等收尾加工，减少下游处理成本。
4. 保持return语法安全：推荐return ({ ... })单行书写风格，规避 ASI 陷阱与跨行可读性问题。
5. 结果位置因触发方式而异：Webhook 调用方从 HTTP 响应体取result；应用内触发时，工作流查询的返回数据即 Response 节点结构，与常规查询一致。
6. 执行环境限制：Response 节点的 JS 在isolated-vm沙箱中求值，且默认执行超时受WORKFLOW_TIMEOUT_SECONDS（默认 60 秒）约束（见 AGENTS.md），因此返回表达式应保持轻量，避免在响应阶段做重计算。

小结

Response 节点是 ToolJet 工作流对外输出能力的核心：一条return语句即可把任意节点数据组合为结构化响应，配合 JavaScript 内置方法可以实现数据裁剪、排序、聚合等精细控制；在执行层面，Webhook 触发时结果进入 HTTP 响应（含可自定义的状态码），应用内触发时则以常规查询格式交付。结合执行服务中processResponseNode与buildResponseNodeMetadata的职责划分（见 AGENTS.md），你既可以把它当作"数据出口"，也可以进一步利用自定义状态码机制，让工作流在对接外部系统时拥有更完整的 HTTP 语义。

【免费下载链接】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