資料與電子表格 · CSV 更清理

在 CSV 和 JSON 之間轉換：形狀、類型和遺失的內容

2026年5月4日 · 工作原理

csv json 資料格式

CSV 是平面文字，JSON 是巢狀的類型化資料，因此它們之間的轉換涉及決策。這篇文章解釋了表格資料的常見 JSON 形狀、如何推斷類型以及什麼不能在往返過程中倖存下來。

API 需要 JSON，匯出為 CSV，每個數字都以字串形式到達 - 為什麼兩種格式在類型上不一致

電子表格匯出可以顯示 42，而無需說明這些字元是否表示計數、產品代碼或識別碼。 JSON 可以區分數字和字串，但 CSV 來源無法提供這種差異。因此，ToolAcre 選擇保守的表示形式：每個單元格都變成 JSON 字串，包括數字、真實的單字和空白單元格。

此決定可使 0012 等文字保持完整，並使 API 整合的轉換可預測。這也意味著下游程式碼必須在進行算術之前將欄位轉換為自己的模式。將產生的檔案視為已鍵入的檔案只會將假設從轉換器轉移到不太可見的應用程式程式碼。

此路由產生一個頂層數組，其中每個資料行都有一個物件。標題單元格成為物件鍵，並從相同的列位置取得值。空白的第三個標頭將變為column_3，而名為id 的第二個標頭將變為id_2，而不是覆蓋第一個id 欄位。

乾淨、唯一的名稱很有用，但轉換器不會小寫、音譯或替換空格。它僅在計算密鑰時修剪標頭，然後在需要時發明位置名稱或數字後綴。如果 API 需要 customer_email 而不是客戶電子郵件，請在依賴輸出協定之前故意重新命名該欄位。

概述建議將陣列的陣列和以列導向的物件作為選用目標。它們是合理的資料設計，但這個介面不提供它們。它的輸出總是由第一個 CSV 行鍵控的 JSON 平面記錄數組，縮排兩個空格以進行可讀檢查。

這種狹窄的選擇消除了列名所在位置的歧義，並使每個記錄的形狀都相似。如果另一個消費者需要數組，請在該消費者的模式下轉換下載的 JSON 。聲稱 ToolAcre 在多個佈局中進行選擇將描述配置或面板程式碼中不存在的控制項和分支。

不會發生類型猜測。 CSV 文字 42 變成“42”， false 變成“false”，空白變成“”而不是 null。這在工具記錄和實作中是明確的，它將單元格直接對應到字串屬性。該路由不會檢查列並決定所有非空值都是數字。

保留字串也將本文與電子表格應用程式更改前導零、日期和長標識符的已發表討論區分開來。這裡的重點是轉換器的實際契約：它避免了此類強制。消費者仍然負責解析已知數量並保持標識符不變。

在相反的方向上，ToolAcre 接受一個頂層 JSON 數組，其項目是物件。它按照第一次看到的順序，根據每個物件的鍵的並集建立列，因此後面的記錄引入的欄位不會遺失。缺失、空和未定義的屬性將變為空 CSV 單元格。

儲存在屬性內的物件或陣列在該單元格內序列化為 JSON 文字。這保留了文字表示，但不會將巢狀結構轉換為附加的列或行。非數組根和包含原始值的數組將被拒絕，因為兩者都不符合此路由支援的表模型。

考慮名稱、活動、計數，然後是 Ada、true、007。 JSON 結果是一個數組，其中包含名為「Ada」、活動「true」和計數「007」的物件。將該平面物件數組轉換回來會產生相同的三個文字單元格，因為沒有類型推斷刪除零或轉換布林值單字。

現在在另一個值之前新增一個空白標題。 JSON 鍵變成column_4，因此即使來源名稱遺失，資料仍然可存取。然而，在標題寬度之外添加一個額外的單元格，載入器會警告有關參差不齊的行；該剩餘單元格沒有密鑰並不存在於 JSON 中。

此路由不是模式驗證器、遞歸扁平化器或流 JSON 處理器。它接受一種記錄的形狀並報告無效的 JSON 或具有特定錯誤的不受支援的根。深度嵌套的記錄需要圍繞其領域設計的映射，而不是自動承諾鍵中的標點符號會建立結構。

輸入檔檢查允許檔案達到配置的 50 MB，而 CSV 解析發生在工作執行緒中。這些事實並不能建立流：檔案文字和完成的行仍然會具體化以進行轉換。對於非常大的 JSON 工作流程，請使用其實現明確記錄增量解析的系統，而不是在此處推斷它。

轉換是一組可見的選擇：第一行作為鍵，平面物件作為記錄，字串作為值。 ToolAcre 讓這些選擇變得穩定，而不是根據樣本進行猜測。空白和重複的標題接收確定性密鑰，而參差不齊的輸入在未命名的剩餘值可能不被注意地消失之前出現。

使用預覽確認分隔符號和行形狀，解決警告，然後下載或複製 JSON。產生的檔案適合了解自身架構的程式碼。它有意不替代該模式，並它的限制是在格式更改期間保護文字 ID 的原因。