工作流接入外部 API 时的数据映射校验方法

在 Coze 工作流中接入外部 REST API 时，最隐蔽的故障类型其实是数据映射错误。接口返回 HTTP 200，不代表后续节点能正确消费返回体；真正的中断往往发生在请求成功之后。常见表现有：上游把 data 当成对象返回，下游节点却按数组遍历；接口字段叫 user_id，工作流里引用的却是 userId；空数据时响应体里的 data 字段为 null，后续节点却直接取 data.list，于是一条空数据记录让整个工作流进入错误分支。

下面这套方法不依赖 Coze 的某个固定界面或隐藏开关。只要能在一个 HTTP 请求节点前后插入少量可执行逻辑，就能按同样思路落地。

先做映射清单，再做类型校验

外部 API 的数据映射不是一个“配置项”，而是从“上游变量 → 请求参数 → 响应结构 → 下一节点入参”的整条链路。建议在写任何校验代码前，先整理一张映射表：

映射表同时服务于联调和排障。当流程偶尔失败时，先拿出这张表，再打开日志对照，往往比直接读错误提示更快定位到是出站参数错了，还是入站解析错了。

对出站参数做防御性归一化

请求体发送前，不要依赖运行时隐式类型转换。字符串 'false' 可能被一些解析器转换为 true；数字 0 可能被当作空值丢弃；日期对象在不同节点之间传成字符串后时区会偏移。把出站字段显式转成目标类型，是成本最低的一道防线。

在支持脚本或自定义代码的工作流中，可以把以下函数放到请求前的代码节点里；如果平台没有代码节点，也可以用内置转换节点的连续赋值实现同样的逻辑：

function str(value) {
  if (value === null || value === undefined) return '';
  return String(value).trim();
}

function num(value) {
  if (value === null || value === undefined) return null;
  const n = Number(value);
  if (!Number.isFinite(n)) throw new Error('number 转换失败: ' + value);
  return n;
}

function arr(value) {
  if (value === null || value === undefined) return [];
  return Array.isArray(value) ? value : [value];
}

这里有一个容易被忽略的硬边界：如果接口主键是 int64，而工作流脚本运行在 JavaScript 类型的运行时环境中，不要把大整数压进 Number。超过 Number.MAX_SAFE_INTEGER 的 ID 用字符串传递，否则精度丢失后，后续按 ID 幂等或关联都会失败。

解析响应时做最小结构校验

外部返回的 response body 不是可信输入，即使状态码为 2xx。常见的错误处理只判断 HTTP 状态码，忽略了业务状态码和结构变化。建议在解析节点内做一个“必要结构检查”：

function parseData(raw) {
  let body = raw;
  if (typeof body === 'string') {
    body = JSON.parse(body);
  }
  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
    throw new Error('响应体不是 JSON 对象');
  }
  if (body.code !== 0) {
    throw new Error('业务错误: ' + body.code + ' ' + body.msg);
  }
  if (body.data === null || typeof body.data !== 'object' || Array.isArray(body.data)) {
    throw new Error('响应缺少 data 对象');
  }
  if (body.data.items !== undefined && !Array.isArray(body.data.items)) {
    throw new Error('items 字段应该为数组');
  }
  return body.data;
}

这段示例假设响应合同是 { code, msg, data }，真实集成时必须按 API 文档改。但要注意：校验 items 时，用 Array.isArray 判断，不要用 if (data.items)。空数组长度为 0，也是合法数组；如果某些字段在特定场景下由上游返回 null，要单独允许 null 或设置默认值，不要把所有 falsy 值一刀切。

用更技术的说法，这是在用 JSON Schema 的最小子集：required、type、items。对工作流场景来说，完整 JSON Schema 未必必要，先锁定这几个维度就能避免大部分静默故障。

错误分支和重试策略：先分类再操作

不是所有外部 API 失败都适合重试。可以按三类处理：

• 参数或权限错误（400、401、422）：属于请求本身问题，重试不会成功，应该进入错误分支并通知配置负责人；
• 限流或瞬时故障（429、5xx、超时）：可以重试，但必须有次数上限、间隔递增，不能无限重试；
• 传输成功但业务错误（HTTP 200 但 body.code 非 0）：不能只凭 HTTP 状态判断是否成功，且这类错误下的重试要特别谨慎。

最后一种最容易造成重复创建。当请求超时后发起重试，原请求可能已经到达服务端并完成写操作。如果工作流能生成唯一 requestId，就把它放进请求头或请求体传给上游，让上游以该 ID 做幂等。上游不支持幂等时，至少要把 requestId 写进日志，后续人工核对也有一条完整链路。

用调用前后日志还原数据流

排查数据映射问题，最直接的动作是“调用外部 API 前打一条日志，调用后打一条日志”。调用前记录 method、url、脱敏后的 headers、请求体；调用后记录状态码、响应体摘要、以及映射后的工作流变量值。不要整段打印响应，尤其不要打印包含个人信息的字段；响应内容只保留前 200 个字符即可。

日志里需要出现一个贯穿全流程的唯一标识。建议在流程入口生成 requestId，并从外部调用节点开始把它透传到后续节点。这样当问题表现为“第三个节点收到空值”时，能靠 requestId 把中途各节点的日志串联起来，确认是哪个环节丢掉了字段。

推荐的落地顺序

新接入一个外部 API 时，按这四步做，能减少来回试错的成本：

1. 用固定样本响应测试解析函数，不直接拿生产接口联调。把 mock 响应输入到解析节点中，验证字段路径和错误信息是否准确。
2. 将请求体参数与映射表逐字段对照，尤其要检查数组和嵌套对象是否被拍平。
3. 接入真实 API 后，打开调试日志，分别观察一次成功执行和一次故意失败执行。
4. 在错误分支接一个包含上下文的通知，而不是只抛异常。通知里带上 requestId、节点名、上游状态码，后续排查时不需要再翻整个流程日志。

做好这些检查后，工作流与外部 API 的数据映射问题会被限制在最小范围：出站前、入站后、以及节点间变量转换这三个边界上。每次外部接口返回结构变化，都只需要修改最靠近接口的那一个校验节点。