Appearance
JSON 反序列化节点
JSON 反序列化节点用于把一个合法 JSON String 解析成工作流中的结构化变量。解析后可以在下游节点中按字段名引用对象属性，或把数组交给循环、批处理等节点继续处理。
该节点只处理 JSON 语法和已配置的输出结构，不会从普通自然语言中提取信息，也不会自动修复 Markdown 代码围栏、单引号、注释或尾随逗号等非标准 JSON 内容。
配置要点
| 项目 | 规则 |
|---|---|
| 输入 | 固定一个名为 input 的 String；一次解析一个 JSON 字符串，批量字符串需配合批处理节点。 |
| 输出根类型 | 默认 Object，也可选择 String、Integer、Number、Boolean、Time、List 或支持的数组类型。 |
| 输出字段 | Object 或 Array<Object> 可手工添加嵌套字段；没有固定层数上限。 |
| 输出结构 | 声明下游可引用路径和类型转换规则，但不会裁剪未声明字段。 |
| 字段维护 | 按接口样例手工维护字段、类型和嵌套结构。 |
适用场景
- 把 HTTP 请求节点返回的
bodyString 转成可引用的对象字段。 - 解析数据库 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> 可以声明每个数组元素的对象结构。没有固定三层限制，但层级越深，配置、排错和下游引用越复杂，建议只声明业务真正需要引用或转换的路径。
配置输出结构
节点面板通过手工添加字段和类型来维护输出结构。请按接口响应示例建立字段树；接口字段经常变化时，应同步维护文档、工作流配置和试运行样例。
输出结构的实际作用
输出结构同时承担三项职责：
- 让声明的字段出现在下游变量选择器中。
- 对实际存在的已声明字段递归执行有限类型转换。
- 使用生成的输出 Schema 校验结果类型。
它不是字段白名单过滤器。未声明字段仍可能保留在实际 output 对象中，只是不会自动出现在下游变量选择器的已声明结构中。
下面的真实试运行输入包含未声明字段 extra，并把 age、active 作为字符串传入：
输出结果中：
age从字符串"18"转换为 Integer18。active从字符串"true"转换为 Booleantrue。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 序列化节点配合
典型往返流程：
- Object/Array 经 JSON 序列化节点 变成 String。
- String 经过 HTTP、数据库或消息通道传输。
- JSON 反序列化节点把 String 恢复为结构化变量。
序列化与反序列化并不保证对象字段顺序保持一致。判断数据是否一致时，应按字段和值比较，不要比较 JSON 原始字符串顺序。
与 HTTP 请求节点配合
HTTP 请求节点的 body 固定为 String，即使服务返回 application/json，也不能直接引用 body.data.id。正确做法是：
- 将 HTTP 节点的
body引用到本节点input。 - 按实际响应顶层类型设置
output。 - 手工声明下游需要引用或需要转换的字段。
- 使用成功与失败响应样例分别试运行。
接口可能在非 2xx 响应中返回另一套 JSON 结构。只为成功响应声明字段，并不能保证错误响应也能通过校验。完整 HTTP 行为请参见 HTTP 请求节点。
嵌套层级与大型 JSON
输出树和运行时递归处理没有固定三层限制，但这不代表应无限嵌套：
- 只声明下游实际需要选择或转换的字段。
- 深层数组和对象会增加 Schema、传输和调试成本。
- 大型 JSON 应避免在多个节点间反复序列化与反序列化。
- 结构长期稳定且被多处使用时，应抽象为明确的接口契约或插件。
错误类型与排查
| 错误 | 常见原因 | 处理方法 |
|---|---|---|
| 参数值不可为空 | input 没有常量或上游引用 | 补充合法 String 输入 |
JSON_DESERIALIZE_FAILED | 输入不是严格 JSON | 检查代码围栏、引号、逗号、注释和前后说明文字 |
JSON_DESERIALIZE_OUTPUT_INVALID | 解析值经过转换后仍不符合输出 Schema | 核对顶层类型、字段类型、数组元素类型与样例 |
JSON_TRANSFORM_INPUT_REQUIRED | 运行时没有取得配置名为 input 的参数 | 检查上游连线、变量引用和运行输入 |
发布前检查
input是否为 String，且常量或上游引用有效。- 输入是否为严格 JSON，没有 Markdown 围栏、注释、尾随逗号或额外文字。
output根类型是否与 JSON 顶层值一致。- 输出字段名是否合法、同级不重复。
- 数值、布尔和数组元素类型是否与真实响应一致。
- 是否误以为未声明字段会被自动删除。
- 下游需要引用的字段是否都已在输出结构中声明。
- 是否错误依赖对象字段顺序。
- 是否使用成功、失败、空值、缺字段、类型变化和深层嵌套样例完成试运行。
- 输入中是否可能包含敏感信息，调试日志和截图是否已脱敏。
常见问题
为什么合法 JSON 仍然解析失败？
先确认传入的是 String 而不是已经解析好的 Object，并检查字符串前后是否有代码围栏、提示文字或不可见字符。JSON 必须使用双引号，不能有注释和尾随逗号。
为什么字段配置正确，但节点提示输出类型不匹配？
核对 JSON 顶层类型和 output 根类型。例如数组不能使用 Object 根类型；字符串 "18岁" 也不能按 Integer 成功转换。
为什么没有配置的 extra 字段仍然出现在运行结果中？
输出结构不负责裁剪字段。它声明下游可选路径，并对已声明字段执行转换与校验。需要白名单结果时，在下游显式构造新对象。
为什么运行结果中有字段，但下游变量选择器看不到？
该字段没有在输出结构中声明。实际运行结果可以保留额外字段，但下游编辑器只能稳定提供已声明的路径供选择。
为什么 "18" 变成了 18？
输出结构把该字段声明为 Integer，运行时会尝试把可解析的数字字符串转换成整数。这是节点的类型转换行为。
如何配置输出字段？
请按接口样例手工添加输出字段、类型和嵌套结构。
是否只能解析三层？
不是。前端和运行时没有固定三层限制；仍建议控制嵌套深度，只声明业务需要的字段。
如何解析 JSON 数组？
把 output 根类型改为与数组元素相符的数组类型。对象数组使用 Array<Object>，并在元素对象下声明需要引用或转换的字段。