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 檔案。