JSON 字段提取、转换与数据血缘

目标与适用范围

按路径提取 JSON 字段，用 JSONata 重塑负载，并记录字段级来源与转换过程；不把血缘记录当作业务语义校验。
本指南将当前任务范围转化为可复核的交付结果。请保留源文件、中间产物和关键判断，让后续协作者能够理解检查了什么以及为什么这样处理。

准备证据并作出选择

• 准备一份有代表性的 JSON 输入样本、要检查的字段路径，以及小型预期输出样本或目标结构。

• 先写好 JSONPath 表达式和 JSONata 表达式，并明确缺失字段、null 值和数组的处理方式。

• 保留原始输入和转换结果，以便之后复核字段计数与 lineage 覆盖率。

• 决策点: 当前问题是选择字段，还是重塑结构？. 需要按路径定位或统计源值时使用 JSONPath 查询工具；需要重命名、嵌套、过滤或组合字段形成新负载时使用 JSONata 查询转换工作室。

• 决策点: 字段应该是直接复制、派生，还是缺失？. 在转换前先作出约定。直接复制的字段保留源路径，计算字段记录依赖和表达式，缺失字段则明确记为缺失，不要为了让样本通过而臆造值。

• 决策点: 怎样让结果可复核？. 验收前必须保留输入与输出样本、请求字段与产出字段的计数，并为每个输出字段提供 lineage 覆盖记录。

按步骤完成工作流

1. 绘制源 JSON 路径

打开代表性负载，识别对象和数组边界，并在编写转换前列出预期输出字段。 使用 jsonpath-query-tool.

2. 提取并统计源字段

运行 JSONPath 表达式，保存命中值，并记录请求、命中、空值和缺失数量，让路径错误在早期暴露。 使用 jsonpath-query-tool.

3. 重塑输出负载

对选中的数据应用 JSONata 表达式，与预期输出样本对比，并记录重命名、过滤、嵌套或派生字段。 使用 jsonata-query-transform-studio.

4. 追踪血缘并完成验收

从输入路径经过 JSONata 步骤连接到输出字段，生成字段级 lineage 记录，检查覆盖率，并保留未解决的缺口供复核。 使用 json-data-lineage-tracer.

交付前验收结果

• 保留输入样本、路径清单和输出样本，并写明请求、命中、缺失和产出字段的数量。
• 转换后的负载符合声明的目标结构，使用同一输入和 JSONata 表达式可以重现。
• 每个输出字段都有源路径或依赖关系以及转换步骤；派生字段和缺失字段被明确标记。
• 记录不宣称已经证明业务语义、领域规则或下游应用行为正确。

常见问题

• 有了 lineage 记录就能证明业务含义正确吗？ 不能。它说明字段来自哪里以及经历了什么转换；值是否符合业务预期，仍需领域负责人审阅。
• 什么时候用 JSONPath，什么时候用 JSONata？ 用 JSONPath 查找、选择和统计源数据；当字段需要新结构、重命名、过滤或派生时，再用 JSONata。
• 请求的路径不存在时应该怎样处理？ 在证据中保留缺失路径和缺失计数，再按预先声明的规则决定省略或输出 null。不要为了让样本通过而猜测字段值。
• 这个流程能验证线上 API 或生产数据管道吗？ 它面向给定的 JSON 样本和可审阅的转换证据，不会自动监控生产、部署 API 或证明下游业务行为。