ToolJet 接 REST 接口、把返回字段映射到表格和表单

接口在 ToolJet 里能返回 200，只说明请求通了；表格拉不出数据、表单提交后字段丢失，通常是数据源层的鉴权、查询层的返回结构、组件层的绑定表达式这三处没有分开处理。建议先把一条 GET 查询的原始返回看清，再把数组绑到表格、把表单值组装成 POST 请求体，最后给失败加上可见提示。

多数情况不需要为每个字段写转换代码：鉴权配置放数据源层，单条查询只在必要时覆盖请求头；表格通过 Data 绑定整个数组，嵌套字段在列表达式里用 row.xxx.yyy 读取；表单值组装进 JSON 请求体后提交，用运行记录确认状态码和响应体。返回结构不确定时，先看原始返回再写表达式，空数组不等于请求失败。

建 REST 数据源并确认鉴权信息放置层级

数据源层放跨查询共用的东西：Base URL、认证方式（Bearer Token、Basic Auth 或自定义 Header）、默认请求头。同一个 API 的多个查询共享一份鉴权，换 token 时只改一处，不用逐条查询改。Token 建议放在环境变量或密钥里，通过 {{secrets.xxx}} 之类的引用注入，不要直接写在组件属性中。

单条查询需要覆盖的是差异部分：某个接口要求不同的 Content-Type，或者临时追加一个追踪头。在查询的 Headers 面板里写 key/value 即可，同名会覆盖数据源层的默认值。通用骨架如下，字段名按实际 API 替换：

数据源 REST：
  Base URL: https://api.example.com
  Auth: Bearer Token = {{secrets.API_TOKEN}}
  Headers: Accept: application/json

查询 restGetUsers（GET）：
  URL: /v1/users
  Params: page=1, size=20
  Headers: X-Trace-Id: {{components.traceInput.value}}

验证方式：保存数据源后先跑一条最简单的查询，看状态码是 200 还是 401/403。401 多半是鉴权层级放错，先回数据源层确认，而不是在查询里再塞一个 Authorization 头。

配一条 GET 查询并查看原始返回

查询面板里选 Method 为 GET，URL 填相对路径或完整地址；带查询字符串的参数优先填在 Params 面板，而不是手拼在 URL 后面，这样运行记录里能分开看到参数。点运行后，响应区域通常会显示状态码、耗时和返回体，切到原始返回（Raw / JSON）视图就能看到真正的结构。

运行后需要确认两件事：顶层是数组还是被包了一层，比如 { code, data: [...] } 或 { items: [...] }。返回结构决定表格绑定写 queries.restGetUsers.data 还是 queries.restGetUsers.data.data。如果返回体里还有分页字段，也一并记下来，后面做翻页时用得到。状态码非 2xx 时不要急着改绑定，先处理鉴权和参数。

把数组结果绑定到表格并处理嵌套字段

表格的 Data 属性绑定数组本身，例如 {{queries.restGetUsers.data.data}}。列绑定到数组元素的字段，嵌套对象用点号或方括号向下取：

列 name:  {{row.name}}
列 部门:  {{row.org.dept.title}}
列 邮箱:  {{row.contact?.email}}
列 标签:  {{row.tags?.[0]?.label}}

如果某列整列空白，先看原始返回里对应路径是否存在，再检查是否少写了一层。路径不存在时表达式通常返回空值，列显示空白，而不是报错，所以空白不一定是绑定语法错。返回空数组时，表格一般显示无数据占位，不会报错，此时应回运行记录确认接口确实返回了空列表，还是 data 路径取错了。

嵌套层数多、多个列都要展开时，可以在查询里加一步 Transformations，把数组拍平后再交给表格。示例只做映射，不改业务含义：

return (data.data || []).map(u => ({
  id: u.id,
  name: u.profile && u.profile.name,
  dept: u.org && u.org.dept && u.org.dept.title
}));

注意先确保原始返回没问题再加转换，否则排错时会被两层结构同时干扰。是否用转换取决于列的数量：只有一两列嵌套，直接写 row 路径更省事。

用表单收集输入并提交 POST 查询

表单里放好输入组件，提交按钮的点击事件触发一条 POST 查询。请求体优先用 JSON，字段值通过组件数据引用。参考骨架：

Method: POST
URL: /v1/users
Headers: Content-Type: application/json
Body（JSON）:
{
  "name": "{{components.form1.data.name}}",
  "email": "{{components.form1.data.email}}",
  "age": {{components.form1.data.age || null}}
}

字符串字段用引号包住，数字或布尔字段不要加引号，否则后端收到的是字符串。如果输入内容本身可能带引号，先做一次转义或改用组件值对象整体序列化。提交后同样看状态码和响应体：201 或 200 表示写成功，422、400 多半是字段校验问题。成功后可以触发一次列表查询刷新表格，形成写后读的闭环。

给失败情况加上提示并看运行记录

查询失败不应该只体现在表格没变化。可以在查询的失败事件里配置通知或提示，把状态码和错误消息暴露出来；也可以在按钮上根据查询状态显示禁用或加载中。判断条件通常读查询对象的 isLoading、error 或 status 一类属性，具体名称以当前版本的查询面板为准。

运行记录里重点看三处：请求实际发出的 URL 和参数、请求头里是否有鉴权信息、响应状态码和返回体。参数拼错、Content-Type 不一致、token 过期，都会在这里露出。把失败查询的参数和响应原文一起复制出来，比在组件表达式里反复猜更快定位。