NDJSON 完整指南：换行分隔 JSON 详解

NDJSON 规范

github.com/ndjson/ndjson-spec 上的官方 NDJSON 规范故意保持简洁。它定义了一种在单个文本流中序列化多个 JSON 值的简单约定。核心规则很直接：

规范明确避免向格式添加头信息、元数据或 Schema 信息。这使 NDJSON 尽可能简单，并与标准 Unix 文本处理工具兼容。每一行允许任何有效的 JSON 值，尽管在实践中大多数 NDJSON 文件包含具有一组一致键的 JSON 对象。

• 每一行必须包含恰好一个有效的 JSON 值（对象、数组、字符串、数字、布尔值或 null）。
• 行由换行符 '\n' (U+000A) 分隔。回车符 '\r' (U+000D) 可以出现在 '\n' 之前，但不是必需的。
• 最后一个 JSON 值之后的尾随换行符是允许的但不是必需的。
• 每个 JSON 值内部不得包含未转义的换行符。

由于规则最少，NDJSON 可以从任何具有 JSON 序列化器的编程语言轻松生成。只需序列化每条记录，追加一个换行符，然后写入输出。无需闭合括号、无需尾随逗号、无需包围数组结构。

NDJSON MIME 类型：application/x-ndjson

NDJSON 的注册 MIME 类型是 application/x-ndjson。此内容类型用于 HTTP 头中，表示响应体包含换行分隔的 JSON 数据。许多流式 API，包括 GitHub API、Docker Registry API 和 Elasticsearch 批量 API，都使用此 MIME 类型来传递 NDJSON 响应。

Content-Type: application/x-ndjson

# Example: curl a streaming API
curl -H "Accept: application/x-ndjson" https://api.example.com/events/stream

# Example: Express.js response
res.setHeader('Content-Type', 'application/x-ndjson');
res.write(JSON.stringify(record) + '\n');

一些 API 也接受 application/json-seq (RFC 7464) 或 text/plain 作为替代。然而，application/x-ndjson 是换行分隔 JSON 流最广泛采用的 MIME 类型。在构建流式传输 JSON 记录的新 API 时，请使用 application/x-ndjson 以获得最大兼容性。

NDJSON 在 HTTP 流式 API 中的应用

NDJSON 是传递实时数据的 HTTP 流式 API 的事实标准。当服务器发送 NDJSON 响应时，客户端可以在第一条记录到达时立即开始处理，无需等待整个响应完成。这比返回大型 JSON 数组更快、更节省内存。

使用 NDJSON 流式传输的热门服务包括 Docker Registry（镜像层事件）、Elasticsearch（批量操作）、Apache CouchDB（变更订阅）以及许多现代事件驱动 API。这种模式在 Server-Sent Events 替代方案、实时日志跟踪和 Web 应用程序中的渐进式数据加载中效果很好。

import express from 'express';

const app = express();

app.get('/api/events/stream', (req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');
  res.setHeader('Transfer-Encoding', 'chunked');

  // Simulate streaming events
  let id = 0;
  const interval = setInterval(() => {
    id++;
    const event = {
      id,
      type: 'heartbeat',
      timestamp: new Date().toISOString(),
    };
    res.write(JSON.stringify(event) + '\n');

    if (id >= 100) {
      clearInterval(interval);
      res.end();
    }
  }, 100);

  req.on('close', () => clearInterval(interval));
});

app.listen(3000);

async function* readNdjsonStream(url) {
  const response = await fetch(url, {
    headers: { 'Accept': 'application/x-ndjson' },
  });

  const reader = response.body
    .pipeThrough(new TextDecoderStream())
    .getReader();

  let buffer = '';
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += value;
    const lines = buffer.split('\n');
    buffer = lines.pop();
    for (const line of lines) {
      if (line.trim()) yield JSON.parse(line);
    }
  }
  if (buffer.trim()) yield JSON.parse(buffer);
}

// Usage
for await (const event of readNdjsonStream('/api/events/stream')) {
  console.log('Received:', event);
}

NDJSON 与 JSONL：互操作性

NDJSON 和 JSONL (JSON Lines) 是功能上完全相同的格式。两者都是每行存储一个 JSON 值，由换行符分隔。一个有效的 NDJSON 文件同时也是有效的 JSONL，反之亦然。您可以将 .ndjson 文件重命名为 .jsonl（或反过来），无需更改任何一个字节的内容，读取一种格式的每个工具都会读取另一种。

唯一的差异是表面的：NDJSON 来自 github.com/ndjson/ndjson-spec，使用 .ndjson 扩展名和 application/x-ndjson MIME 类型，而 JSONL 来自 jsonlines.org，使用 .jsonl 扩展名。在实践中，大多数开发者将这两个名称视为同义词。如果您的项目已经使用 JSONL，则无需迁移到 NDJSON；如果一个库说它支持 NDJSON，它也会无需任何更改地处理您的 .jsonl 文件。