JSON 规范化与数据交换工作流

目标与适用范围

把结构化来源转换为经过核对的 JSON 表示，再按下游需求导出为表格、配置、文档、API、XML、CSON、EDN、BSON 或 UBJSON。
本指南将当前任务范围转化为可复核的交付结果。请保留源文件、中间产物和关键判断，让后续协作者能够理解检查了什么以及为什么这样处理。

准备证据并作出选择

• 保留未改动的代表性源文件，并写清消费方要求的模式、字段名、空值策略、日期格式和数值精度。

• 先判断来源是记录型表格、配置语言、类标记文档、GraphQL 负载还是二进制 JSON，再选择转换器。

• 决策点: 实际来源应走哪条分支？. 只选择与真实语法匹配的导入器。CSV 行集、Terraform 风格 HCL、Markdown 文档、BSON 负载和 GraphQL 响应的结构假设并不相同。

• 决策点: JSON 是交接格式还是内部检查点？. 如果消费方接受 JSON，就把它保留为已审查交接件；否则只导出一个明确目标，并记录有意的扁平化、字符串化或层级变化。

• 决策点: 往返时哪些字段必须不变？. 检查承载业务含义的字段：编号及前导零、null 与空字符串、嵌套数组、日期、小数精度、键名和二进制类型。

按步骤完成工作流

1. 按真实来源语法导入 JSON

根据输入选择分支：解码 BSON 或 UBJSON，解析 CSON 或 EDN，把 GraphQL 响应转换为 JSON，或从 Markdown 提取结构化内容。原始文件要与 JSON 检查点一并保存，便于追溯歧义。 使用 bson-converter, ubjson-converter, cson-to-json, edn-to-json, graphql-to-json, markdown-to-json.

2. 把表格来源建模为明确记录

处理 CSV 或 Excel 时先确认表头行，保留看似数字的标识符，并决定 XLSX 交接中嵌套 JSON 是否需要展开或还原。继续前比较行数和几处复杂单元格。 使用 csv-to-json, excel-to-json, xlsx-json-transformer.

3. 转换配置但不擅自补充语义

YAML、TOML 或 HCL 只用于手头真实格式。检查嵌套、带引号标量、数组和配置专有结构；注释与重复键行为未必能在 JSON 中保留。 使用 yaml-json-converter, toml-json-converter, hcl-json-converter.

4. 交付消费方真正需要的表示

只把已核对 JSON 导出为下游所需目标：扁平记录用 CSV，层级交换用 XML，查询型负载用 GraphQL，审阅用 Markdown，语言专用消费方用 CSON 或 EDN。用代表性重导入或解析器验证选定目标。 使用 json-to-csv, json-to-xml, json-to-graphql, json-to-markdown, json-to-cson, json-to-edn.

交付前验收结果

• 选用的转换器符合真实来源语法，未把无关分支说成必经步骤。
• JSON 检查点具有预期记录或对象结构、字段名、嵌套、空值语义和代表性值。
• 目标工件符合消费系统的语法与已记录的损失边界，包括表格扁平化或配置注释。
• 定向往返或解析比较验证了约定关键字段，而不只是确认输出文件能被打开。

常见问题

• 一份文件需要经过所有转换器吗？ 不需要。这些步骤是围绕同一 JSON 检查点的受控分支，只选与真实来源和消费方匹配的导入与导出。
• JSON 能保留来源的一切特性吗？ 不一定。注释、重复键、排版意图、电子表格公式、二进制子类型和部分配置结构都要在转换前明确审查。
• 如何避免前导零或小数发生变化？ 在契约中把这些字段声明为字符串或固定精度值，并在转换后及目标解析器读取后比较代表性编号和金额。
• 什么时候适合做往返测试？ 当目标被期望可逆时就应做。对于 JSON 转 CSV 或 Markdown 这类有意损失的导出，只比较约定字段并记录不可回传的内容。