JSON 反序列化节点

JSON 反序列化节点用于把一个合法 JSON String 解析成工作流中的结构化变量。解析后可以在下游节点中按字段名引用对象属性，或把数组交给循环、批处理等节点继续处理。

该节点只处理 JSON 语法和已配置的输出结构，不会从普通自然语言中提取信息，也不会自动修复 Markdown 代码围栏、单引号、注释或尾随逗号等非标准 JSON 内容。

当前实现与旧文档差异

本页保留旧文档中“解析 HTTP 响应、一次处理一个 JSON 字符串、配置输出字段”的核心说明，并按当前前端与执行器更正如下：

项目	当前实现	旧文档需要更正之处
输入	固定一个名为 input 的 String	一次只解析一个 JSON 字符串；批量字符串仍需配合批处理节点
输出根类型	默认 Object，也可改为 String、Integer、Number、Boolean、Time、List 或支持的数组类型	不只支持 Object 与少量标量类型
输出字段	Object 或 Array<Object> 可手工添加嵌套字段	当前代码没有旧文档所述“最多三层”的固定上限
JSON 示例导入	当前节点面板没有“JSON 导入”入口	旧文档中的一键导入说明不适用于当前界面，需要手工维护输出结构
字段提取	输出结构声明可选字段和类型，但不会裁剪未声明字段	只配置 name、id 并不表示实际结果只剩这两个字段
类型处理	对已声明字段递归执行有限的类型转换，并按输出 Schema 校验	输出结构不只是下游变量提示，也会影响运行结果与校验

适用场景

• 把 HTTP 请求节点返回的 body String 转成可引用的对象字段。
• 解析数据库 String/Text 字段中保存的 JSON。
• 恢复 JSON 序列化节点产生的 Object 或 Array。
• 将严格 JSON 格式的大模型输出转换为下游可引用变量。
• 把 JSON 数组解析为 Array<String>、Array<Integer> 或 Array<Object> 后交给循环、批处理节点。

以下情况不适合直接使用该节点：

• 输入已经是 Object/Array：直接引用原结构，不要先转成字符串再解析。
• 输入是普通自然语言或 Markdown：先通过模型、代码或文本处理生成严格 JSON。
• 需要过滤、重命名、合并字段：反序列化后再用变量赋值、代码或业务节点处理。
• 需要同时解析多个彼此独立的 JSON 字符串：使用多个节点，或在批处理节点中逐项解析。
• 只需要判断字符串是否为合法 JSON、但不需要结构化输出：可在代码或专用校验节点中处理，并明确异常策略。

节点配置

JSON 反序列化节点由固定 String 输入和可配置输出结构组成。

输入

配置	当前行为
变量名	固定为 input，不可新增、删除或重命名
变量类型	固定为 String，不可切换为 Object/Array
参数值	必填，可以输入常量或引用上游 String 输出

输入必须是完整、严格的 JSON 文本。以下内容会解析失败：

• 空字符串或只有空白。
• 单引号对象，例如 {'name':'小明'}。
• 带 Markdown 代码围栏的内容。
• 含注释、尾随逗号、undefined、NaN 或未加双引号的键。
• 在合法 JSON 前后混入说明文字。

当上游是大模型时，应要求模型只返回严格 JSON，并对不稳定输出配置异常处理。不要假设模型每次都会遵守格式。

输出根节点

输出变量名固定为 output，默认类型为 Object。当前可选择的非文件类型包括：

• String、Integer、Number、Boolean、Time。
• Object、List。
• Array<String>、Array<Integer>、Array<Number>、Array<Boolean>、Array<Time>、Array<Object>。

输出根类型必须与 JSON 顶层值相匹配：

JSON 顶层内容	建议输出根类型
{"name":"小明"}	Object
["A","B"]	Array<String>
[{"id":1},{"id":2}]	Array<Object>
18	Integer 或 Number
true	Boolean
"文本"	String

如果输入顶层是数组，而输出根仍配置为 Object，运行时不会把数组自动包成对象，最终会因输出类型不匹配而失败。

添加输出字段

当根类型为 Object 时，点击右侧“+”可以添加子项。字段名应满足当前编辑器规则：

• 以英文字母或下划线开头。
• 只能包含英文字母、数字、下划线和 $。
• 同级字段名不能重复。
• 不要使用 true、false、null、If、Switch 等受限制名称。

Object 子项还可以继续添加子项；Array<Object> 可以声明每个数组元素的对象结构。当前实现没有旧文档所述固定三层限制，但层级越深，配置、排错和下游引用越复杂，建议只声明业务真正需要引用或转换的路径。

当前没有 JSON 导入入口

旧文档说明可以粘贴 JSON 示例自动生成字段树。当前 JSON 反序列化节点实际面板只提供手工添加字段和类型选择，没有“JSON 导入”按钮。

因此需要按接口响应示例手工建立输出结构。接口字段经常变化时，应同步维护文档、工作流配置和试运行样例，不能依赖旧截图中的导入功能。

输出结构的实际作用

输出结构同时承担三项职责：

1. 让声明的字段出现在下游变量选择器中。
2. 对实际存在的已声明字段递归执行有限类型转换。
3. 使用生成的输出 Schema 校验结果类型。

它不是字段白名单过滤器。未声明字段仍可能保留在实际 output 对象中，只是不会自动出现在下游变量选择器的已声明结构中。

下面的真实试运行输入包含未声明字段 extra，并把 age、active 作为字符串传入：

输出结果中：

• age 从字符串 "18" 转换为 Integer 18。
• active 从字符串 "true" 转换为 Boolean true。
• address.city 按嵌套结构保留为 String。
• 未声明的 extra 仍保留在实际结果中。

因此，如果业务要求只保留白名单字段，应在反序列化之后显式构造一个新对象，不能只依赖输出字段列表。

当前类型转换规则

运行时在 JSON 解析成功后，根据已配置输出结构递归处理对应字段：

目标类型	当前转换行为
Integer	字符串会去除首尾空白后尝试解析整数；数值型小数转换为整数时会截断小数部分
Number	字符串会去除首尾空白后尝试解析浮点数
Boolean	字符串 true、false 忽略大小写并去除首尾空白后转换
String	String 保持不变；null 转为空字符串；其他 JSON 值转换为文本
Object	只对声明且实际存在的子字段继续递归转换
Array	对数组中的每个元素按元素 Schema 递归转换

无法完成转换时，值通常会保留原类型，随后由输出 Schema 校验。如果保留后的类型仍不匹配，节点以 JSON_DESERIALIZE_OUTPUT_INVALID 失败。

类型转换不是通用的数据清洗：

• "18岁" 不能转成 Integer。
• "yes" 不能转成 Boolean。
• Object 不会自动从任意普通字符串中生成。
• 数值转 Integer 会截断小数，不会进行业务意义上的四舍五入。

需要严格、可审计的转换规则时，应在反序列化后使用代码或业务节点显式处理。

与 JSON 序列化节点配合

典型往返流程：

1. Object/Array 经 JSON 序列化节点 变成 String。
2. String 经过 HTTP、数据库或消息通道传输。
3. JSON 反序列化节点把 String 恢复为结构化变量。

序列化与反序列化并不保证对象字段顺序保持一致。判断数据是否一致时，应按字段和值比较，不要比较 JSON 原始字符串顺序。

与 HTTP 请求节点配合

HTTP 请求节点的 body 固定为 String，即使服务返回 application/json，也不能直接引用 body.data.id。正确做法是：

1. 将 HTTP 节点的 body 引用到当前节点 input。
2. 按实际响应顶层类型设置 output。
3. 手工声明下游需要引用或需要转换的字段。
4. 使用成功与失败响应样例分别试运行。

接口可能在非 2xx 响应中返回另一套 JSON 结构。只为成功响应声明字段，并不能保证错误响应也能通过校验。完整 HTTP 行为请参见 HTTP 请求节点。

嵌套层级与大型 JSON

当前前端输出树和运行时递归处理没有固定三层限制，旧文档中的“三层”约束已不适用。但这不代表应无限嵌套：

• 只声明下游实际需要选择或转换的字段。
• 深层数组和对象会增加 Schema、传输和调试成本。
• 大型 JSON 应避免在多个节点间反复序列化与反序列化。
• 结构长期稳定且被多处使用时，应抽象为明确的接口契约或插件。

错误类型与排查

错误	常见原因	处理方法
参数值不可为空	input 没有常量或上游引用	补充合法 String 输入
JSON_DESERIALIZE_FAILED	输入不是严格 JSON	检查代码围栏、引号、逗号、注释和前后说明文字
JSON_DESERIALIZE_OUTPUT_INVALID	解析值经过转换后仍不符合输出 Schema	核对顶层类型、字段类型、数组元素类型与样例
JSON_TRANSFORM_INPUT_REQUIRED	运行时没有取得配置名为 input 的参数	检查上游连线、变量引用和运行输入

发布前检查

1. input 是否为 String，且常量或上游引用有效。
2. 输入是否为严格 JSON，没有 Markdown 围栏、注释、尾随逗号或额外文字。
3. output 根类型是否与 JSON 顶层值一致。
4. 输出字段名是否合法、同级不重复。
5. 数值、布尔和数组元素类型是否与真实响应一致。
6. 是否误以为未声明字段会被自动删除。
7. 下游需要引用的字段是否都已在输出结构中声明。
8. 是否错误依赖对象字段顺序。
9. 是否使用成功、失败、空值、缺字段、类型变化和深层嵌套样例完成试运行。
10. 输入中是否可能包含敏感信息，调试日志和截图是否已脱敏。

常见问题

为什么合法 JSON 仍然解析失败？

先确认传入的是 String 而不是已经解析好的 Object，并检查字符串前后是否有代码围栏、提示文字或不可见字符。JSON 必须使用双引号，不能有注释和尾随逗号。

为什么字段配置正确，但节点提示输出类型不匹配？

核对 JSON 顶层类型和 output 根类型。例如数组不能使用 Object 根类型；字符串 "18岁" 也不能按 Integer 成功转换。

为什么没有配置的 extra 字段仍然出现在运行结果中？

当前输出结构不负责裁剪字段。它声明下游可选路径，并对已声明字段执行转换与校验。需要白名单结果时，在下游显式构造新对象。

为什么运行结果中有字段，但下游变量选择器看不到？

该字段没有在输出结构中声明。实际运行结果可以保留额外字段，但下游编辑器只能稳定提供已声明的路径供选择。

为什么 "18" 变成了 18？

输出结构把该字段声明为 Integer，当前运行时会尝试把可解析的数字字符串转换成整数。这是节点的现行类型转换行为。

为什么旧文档中的 JSON 导入按钮找不到？

当前节点面板没有该入口。请按接口样例手工添加输出字段、类型和嵌套结构。

当前是否仍然只能解析三层？

不是。当前前端和运行时没有固定三层限制；仍建议控制嵌套深度，只声明业务需要的字段。

如何解析 JSON 数组？

把 output 根类型改为与数组元素相符的数组类型。对象数组使用 Array<Object>，并在元素对象下声明需要引用或转换的字段。