什么是 NDJSON？流式记录、语法和用例

Scrapeless Scraping API 返回结构化的 JSON，供下游管道在需要独立记录的行导向流或存储时作为 NDJSON 来呈现。

什么是NDJSON？

NDJSON是一种文本格式，用于表示一系列由换行符分隔的JSON值。每一行物理行包含一个完整的JSON文本。消费者读取一行，将该行解析为JSON，处理结果值，然后移至下一个记录。

规则： 1. 仅输出翻译文本 — 无需解释，无需额外的包装代码块。 2. 保留Markdown/HTML结构（标题、列表、链接、表格）完全不变。 3. 保持任何占位符令牌如@@CODEBLOCK_0@@或@@INLINECODE_0@@完全不变；绝不要翻译、重排序、合并或重格式化它们。 4. 不要添加或删除```代码块，也不要将正常文本包装到代码块中。 NDJSON规范 每个JSON文本都要求符合JSON规则，并且后面必须有换行。它指定使用UTF-8，接受LF和CRLF作为解析的行分隔符，并建议 application/x-ndjson 与 .ndjson 扩展。

NDJSON是围绕JSON的一个框架约定，而不是一个新的对象模型。技术上来说，一行可以包含任何JSON值，尽管逐行对象是日志、大规模导入、导出和数据管道的主要模式。JSON语法保持为由 RFC 8259.

NDJSON 文件是什么样的？

一个产品观察流可能包含三个独立的记录：

{"sku":"A-17","price":34.5,"currency":"USD"}
{"sku":"B-08","price":28,"currency":"USD"}
{"sku":"C-31","price":null,"currency":"EUR"}

没有打开的数组括号，记录之间没有逗号，也没有关闭括号。每一行都可以独立解析。最后一行应该按照 NDJSON 序列化规则以换行符结束，尽管文本查看器并不总是显示最后的分隔符。

格式良好的 JSON 不能作为一个 NDJSON 记录使用，因为缩进会将一个值写在多个物理行上。生产者应将每个值序列化为紧凑形式。一个包含逻辑换行符的字符串仍然有效，因为 JSON 对其进行了转义：

{"id":41,"message":"first line\nsecond line"}

这两个字符反斜杠和 n 在一个物理行上保持在JSON字符串内。JSON解析器在记录框架已经成功后重建换行符。

NDJSON 与 JSON 数组

为什么 NDJSON 适合流式传输

标准 JSON 并未定义两个相邻顶级值之间的边界。写入 {}{} 使解析器没有标准分隔符。NDJSON 将该角色分配给换行符。读取器不需要扫描平衡的括号，因为 JSON 字符串内的括号是普通字符串字符，而物理行边界结束记录。

生产者在记录准备好时可以刷新每一行。消费者可以通过其流接口施加回压，解析一行，验证值，并在处理后释放内存。这使内存使用紧密关联于最大记录和管道缓冲区，而不是整个数据集。

NDJSON 不是唯一的 JSON 序列格式。 RFC 7464 定义 JSON 文本序列 在每个 JSON 文本之前使用 ASCII 记录分隔符字符。该结构可以容忍格式良好的值，因为记录边界不仅依赖于行结尾。生产者和消费者必须就使用哪个序列格式达成一致。

NDJSON 记录设计

一个强大的 NDJSON 流为每一行提供了足够的上下文，以便独立处理。当多个事件形状共享一个流时，包含一个稳定的记录类型或模式版本。包含支持去重的标识符，以防运输可能多次传送同一逻辑记录。仅在有文档格式和时区语义时添加事件和观察时间。

除非合同明确要求编码字节，否则应将大型二进制内容排除在面向行的 JSON 之外。Base64 增大了大小并产生非常长的记录。更好的事件可以携带一个受控对象引用加上完整性元数据，受授权访问时的约束。

排序必须明确。NDJSON 保留物理行顺序，但分布式生产者、分区和并行消费者可能会改变观察到的处理顺序。如果在实体内顺序很重要，请包括一个序列或版本，并定义如何处理间隙和无序记录。

模式验证

有效的 JSON 并不一定是有效的业务记录。一行可能成功解析，而缺少所需的标识符或存储了一个数字，而合同期望一个字符串。在使用之前，验证每个解析值是否符合记录模式。

具有多种记录类型的流可以根据稳定的区分符选择模式。调度程序应拒绝未知类型或将其路由到受控隔离路径。模式版本应定义兼容性，以便消费者在添加可选字段时能够继续。

记录级验证允许批次报告特定失败，而不会丢失可接受记录的位置。存储物理行号、字节偏移（如果可用）、模式错误和一个安全被编辑的记录标识符。不要将机密或敏感有效载荷复制到错误日志中。

常见 NDJSON 使用案例

NDJSON、CSV 和 Parquet

NDJSON 保留嵌套 JSON 结构，并允许具有可选字段的记录。当每个记录都是一行平面表时，CSV 更加紧凑且易于接近。Parquet 添加了类型列存储，用于跨多个记录进行重复分析。

一个通用管道收集或接收 JSON，写入原始 NDJSON 以便于追加跟踪，验证并规范化记录，然后发布 Parquet 以便于分析查询。CSV 对于选定的平面导出给电子表格用户仍然有用。每个阶段有不同的消费者，因此有不同的最佳格式。

压缩和拆分

文本记录通常压缩良好，因为键和值模式会重复。整个文件压缩减少存储和传输大小，但某些编码器使从压缩流的中间开始读取变得困难。可拆分的压缩或独立压缩的块可能更适合并行处理。

仅在完整的记录边界上拆分。通过 JSON 字符串中间的字节范围切割会创建无效片段。需要并行访问的系统可以维护块索引，将流分块成多个对象，或使用为选择性读取构建的存储格式。

连接有效的 NDJSON 文件通常在每个输入以换行符结束时保留有效的行框架。如果一个文件缺乏最终的分隔符，其最后记录可能与下一个文件的第一记录重叠。写入者应始终终止序列化记录，包括最后一个。

安全与操作限制

对总字节、行长度、嵌套深度、字符串长度、数字大小和允许的属性计数施加限制。单个 NDJSON 行可以非常大，除非应用程序执行边界。使用限制缓冲区或流策略读取，这会报告一个超大记录，而不会耗尽内存。

不要将字段作为命令或模板执行。当它们进入 HTML、SQL、shell 或日志上下文时转义值。在 NDJSON 记录后期转换为纯文本时，防止日志伪造。当一个文件可能包含多个租户的数据时，保持其授权在流和记录级别。

如何可靠地处理 NDJSON

1. 将流打开为 UTF-8。 定义如何报告无效字节序列；静默替换可能会改变标识符。
2. 读取一条有界的物理行。 接受一致的行结束符并强制最大记录大小。
3. 通过合同处理空行。 决定它们是被忽略还是被拒绝，并一致应用规则。
4. 解析一个 JSON 值。 拒绝该行尾部的非空白内容并定义重复成员行为。
5. 验证记录模式。 检查类型、必需属性、值限制和支持的版本。
6. 尽可能地幂等处理。 稳定的记录标识符有助于防止当记录出现多次时的重复副作用。
7. 安全地记录进展。 检查点应标识一个持久的记录或字节边界，而不声称处理了不完整的行。

何时不使用 NDJSON

当有效负载较小、必须携带顶层元数据或受益于美观打印时，请使用普通的 JSON 文档。当数据是供电子表格使用者的平面表格时，请使用 CSV。当分析引擎需要列修剪、类型存储和在大型数据集上的压缩时，请使用 Parquet。

当单个值必须包含未转义的物理行格式以供人工编辑时，NDJSON 也是一个不适合的选择。基于记录分隔符的 JSON 序列或框架二进制协议可能更符合这一需求。

结论

NDJSON 为 JSON 交换添加了一条实用规则：每行是一个完整的 JSON 值。该规则支持适合附加的文件、流解析器、记录级验证和有界内存。它不定义业务模式、排序保证、安全政策或交付语义。一种可靠的 NDJSON 工作流程使用紧凑的 UTF-8 记录、显式模式、大小限制、稳定标识符、明确的空行行为和行感知检查点。