教我尊重扁平化的任務在門票上看起來很無聊:"將設定物件匯出到電子表格,以便客戶端可以編輯它。&引用;這些設定是從 Laravel 配置中深度嵌套的 JSON blob,某些地方深三層和四層,混合了特徵標誌陣列。電子表格有列,而不是樹。我需要每個葉值作為客戶端可以在一行中看到的單一平面鍵,編輯和返回,然後我需要從編輯重建精確的嵌套結構,而不會丟失單一數組索引。 JSON 扁平化器所做的就是往返,嵌套到平面,平放回嵌套,並且讓它無損地成為整個遊戲。工具 JSON 展平器 是我為該工作構建的工具,本指南解釋了它是如何工作的以及它在哪裡可以拯救您。
TL;DR: JSON 扁平化器將嵌套物件轉換為單級對象,其鍵是每個值的路徑,因此
{"user":{"city":"Austin"}}成為{"user.city":"Austin"}。 數組被扁平化,其索引位於路徑中 (roles.0). Unflatten 反轉它,從那些點鍵重建嵌套物件和陣列。 Toolz 工具可以無損地執行兩個方向,保留空物件和數組,支援點或括號數組表示法和自訂分隔符,並且完全在客戶端運行,無需上傳和註冊。
我在 Laravel 和 React 上建立 SaaS 並運送 WordPress 插件,因此嵌套 JSON 在我那個時代隨處可見:設定檔、API 有效負載、i18n 訊息目錄、功能標誌儲存。不過,消耗這些有效負載的系統經常需要扁平金鑰。扁平化是結構化資料自然形狀和電子表格、環境變數和點狀金鑰儲存自然形狀之間的適配器。這是一個小操作,可以悄悄地解鎖許多其他煩人的任務。
什麼是 JSON 扁平化器?
JSON 扁平化器將嵌套的 JSON 物件轉換為單級對象,其中每個鍵都是從根到葉值的完整路徑。路徑語法也不是任意的: RFC 6901 定義 JSON 指針,這是尋址文件內一個值的標準方法。嵌套的 {"user":{"name":"Ada","address":{"city":"Austin"}}} 變成公寓 {"user.name":"Ada","user.address.city":"Austin"}. 價值觀沒有任何變化;只有它們的尋址才有效。每一片葉子,無論多麼深,都會有一把鑰匙,詳細說明如何到達它。
數組的處理方式相同,數組索引變成路徑段: {"roles":["admin","editor"]} 展平至 {"roles.0":"admin","roles.1":"editor"}. 鍵中的索引是讓反向操作以正確的順序重建數組的原因。此反向操作不平坦,採用虛線鍵的平坦物件並重建嵌套物件和數組,在每個步驟中決定路徑段是否命名物件屬性或數組索引。當扁平和非扁平使用相同的分隔符號和數組表示法時,它們是精確的逆,並且無損往返是使工具值得信賴的實際工作而不是單向便利的屬性。
我為什麼要先壓平 JSON?
因為許多系統只講平面鍵值對,而虛線路徑是承載嵌套結構而不丟失它的標準方式。最明顯的例子是電子表格。電子表格是一個列網格,並且沒有 " 列在使用者內部位址內的城市。"壓平物件和 user.address.city 成為該值可以駐留在下的單列標題,這正是我的設定匯出票證所需的。
同樣的形狀也出現在許多其他地方。環境變數和 .env 文件是平坦的,映射配置到它們的工具使用點狀或下劃線路徑。國際化庫使用點狀路徑來鍵入字串 checkout.button.label。 功能標誌平台、分析事件模式和許多日誌記錄管道都想要一級金鑰,通常這樣它們就可以獨立索引或查詢每個欄位。在每種情況下,嵌套都是真實且有意義的,並且扁平化將其保留在路徑中而不是丟棄它。當平面表示達到其目的時,不扁平會重建原始物件。如果您也在 JSON 和電子表格之間移動,則具體來說 CSV 到 JSON 轉換器 是那次旅行的表格腿的天然伴侶。
扁平化時如何處理陣列?
數組是人們最常出錯的部分,因此值得精確。數組元素使用其數字索引作為路徑段進行扁平化,這可以保留順序並允許準確地重建數組。 Toolz 工具為該索引提供了兩種符號,它們以不同的語法對相同的資訊進行編碼。
| 輸入 | 點符號 | 括號符號 |
|---|---|---|
{"roles":["admin","editor"]} |
roles.0, roles.1 |
roles[0], roles[1] |
{"items":[{"id":1}]} |
items.0.id |
items[0].id |
{"matrix":[[1,2]]} |
matrix.0.0 |
matrix[0][0] |
點符號寫道 roles.018n 系統結構緊湊,符合多少配置和 i18n 系統鍵入其值。括號表示法寫道 roles[0],它反映了 JavaScript 存取語法和某些查詢語言使用的路徑樣式。兩者都不是更正確;你選擇系統另一端期望的一種。重要的是一致性:無論你使用什麼符號來展平,都使用相同的符號來展平,因為這就是工具知道數字段意味著 "數組索引和引用;而不是"恰好是一個數字的物件鍵。" Toolz flattener 預設為點符號,讓您一鍵切換到括號。
如何使用 JSON 扁平化器?
該流程有兩個方向和幾個選項。首先選擇扁平或不扁平,並在頂部切換。 Flatten 採用嵌套 JSON 並產生點鍵; unflatten 採用點鍵並重建嵌套結構。載入範例會填入您所在方向的工作範例,以便您在貼上自己的資料之前可以看到輸入和輸出的形狀。
將 JSON 貼到輸入框中。對於 flatten,即嵌套物件;對於 unflatten,它是一個平面對象,其鍵是點路徑。輸入必須是有效的 JSON,如果不是,則工具會報告解析器'訊息和問題的位置,而不是向您提供空白輸出,因此很快就會找到雜散尾隨逗號。設定鍵樣式:分隔符號預設為點,當您的鍵已包含點時可以更改,並且數組符號切換之間切換 roles.0 和 roles[0]。 在扁平且匹配的不扁平的情況下保持這兩個設定相同,以便往返對齊。點擊操作按鈕,檢查確認產生了多少頁的鍵數,然後複製輸出或將其下載為 .json 文件。整個事情會在您點擊的瞬間在瀏覽器中運行,不會發送到任何地方。
扁平化是否無損?邊緣情況是什麼?
對於 Toolz 工具,是的,有一個邊緣案例值得了解。標量, null,布林值和數字保持不變。微妙的部分是空容器:一個空的物體 {} 或一個空數組 [] 被保留為葉子值而不是默默地刪除,因此依賴空列表的配置仍然會往返於原來的位置。許多天真的扁平化程式會遺失空容器,這會悄悄改變文件的含義,因此這是一個深思熟慮的選擇。
一個真正的限制是已經包含分隔符號的鍵。如果您的資料有一個物件鍵,其中包含一個文字點,例如 {"a.b":1},當你用點分隔符號平整時,路徑就會變得模糊:不平整無法判斷是否 a.b 是一個鍵或一個嵌套 a 然後 b。 修復方法是將分隔符號變更為未出現在按鍵中的字元(例如斜線或管道),並對兩個方向使用相同的分隔符號。這是您看到的同一類轉義問題 CSV 分隔符號與資料衝突,同樣的解決方案也適用:選擇一個您的值不包含的分隔符號。在該情況之外,平整後跟具有匹配設定的不平整會精確地再現原始文檔,包括數組和空容器。
扁平化和轉換為另一種格式有什麼區別?
扁平化不是格式轉換;而是格式轉換。這是 JSON 內部的重組。扁平化的輸出仍然是 JSON,只是使用單級點鍵而不是嵌套。這與將 JSON 變成真正不同的序列化的轉換器不同,並且知道您需要哪個序列化可以保存一個步驟。
如果您想要配置檔案中表達為 YAML 的相同數據,則 JSON 到 YAML 轉換器 是工具,因為它改變了語法而不是形狀。如果您想要一個描述結構的 TypeScript 介面,以便您的前端知道它正在處理什麼,那麼 JSON 到 TypeScript 轉換器 從樣本中推斷出來。如果您想要一份正式的驗證合同,則 JSON 模式產生器 從範例中匯出 JSON 模式。扁平化位於這些旁邊而不是替換它們:當下游系統需要一級金鑰時,您會變平;當系統需要不同語言時,您會進行轉換。我經常按順序執行這兩項操作,將有效負載展平以將其編輯為列,然後單獨為嵌套版本產生類型,我將其交給 React。用於在該鏈中的任何點漂亮地列印或驗證 JSON, JSON 格式化程式 是我在下一個選項卡中保持開啟的實用程式。
unflatten 如何在數組和物件之間做出決定?
這就是使往返發揮作用的機制,理解它解釋了工具和#39;s 預設值及其一個鋒利的邊緣。當不平坦時讀取鍵喜歡 user.roles.0,它將其分成幾段 user, roles, 和 0,然後引導他們按原樣建構結構。在每一步中,它都會查看下一個段來決定要建立什麼樣的容器。如果下一個段是非負整數,則它形成一個數組;如果它是其他任何東西,它就會形成一個物件。所以 roles.0 告訴工具 roles 應該是一個第一個元素是值的數組,而 address.city 告訴它 address 應該是一個有a的物件 city 財產。
這個單一規則,"整數段表示數組索引,"這就是為什麼具有匹配設定的扁平和非扁平精確再現數組的原因。這也是您選擇的數組符號必須一致的原因。在點表示法中,數組索引和物件鍵都只是點之間的文本,因此該工具完全依賴整數測試。在括號表示法中 [0] 語法在分裂發生之前就明確了意圖。要么有效,但混合它們、用括號壓平和用點壓平,會破壞工具所依賴的訊號。
這是從規則得出的鋒利邊緣:其鍵確實是字串的物件 "0", "1", "2" 一旦扁平化,就與數組無法區分。兩者都產生鍵 0, 1, 2,不扁平會將它們重建為數組,因為這是非常常見的情況。如果您確實需要一個帶有數字字串鍵的物件才能在往返中生存,那麼這是一種情況,即扁平化和不扁平化不會讓您恢復確切的類型,您最好保持該物件嵌套或使用非數字鍵方案。在這樣做的這些年裡,我已經兩次擊中了這種情況,兩次都是在數據中,可以說一開始就建模錯誤,所以預設值對幾乎每個人來說都是正確的交易。保留帶有前導零的數字作為字串背後的務實決策是相同的 CSV 到 JSON 轉換器:該工具針對資料幾乎總是意味著什麼進行最佳化,並記錄罕見的異常,而不是使公共路徑變得尷尬。
我的 JSON 可以安全地貼到這個工具中嗎?
是的,它是架構性的,而不是承諾。解析、展平、展平和序列化都在您自己的瀏覽器標籤內以 JavaScript 形式運行。沒有上傳,沒有伺服器往返,也沒有記錄或儲存任何內容。開啟您的瀏覽器'網路標籤並點擊操作按鈕:沒有請求發出。頁面載入後,您可以斷開與互聯網的連接並繼續工作,因為循環中從來沒有伺服器。
這比看起來更重要,因為 JSON 有效負載正是那種攜帶秘密的東西:配置中的 API 令牌、API 回應中的個人資料、設定 blob 中的內部識別碼。將物件上傳到伺服器的扁平化器會將私人有效負載變成其他人's 日誌行。客戶端處理完全消除了風險,這就是為什麼它是 toolz。dev 上每個工具的預設值。如果你想要完整的推理,我把它放在了 線上工具的資料隱私指南,我用於此類工作的更廣泛的工具包就在我的 web 開發人員工具包指南.
常見問題
壓平 JSON 是什麼意思?
展平 JSON 將嵌套物件轉換為單級對象,其鍵是每個值的路徑。嵌套的 {"user":{"city":"Austin"}} 變成公寓 {"user.city":"Austin"}. 每個葉值都有一個點鍵,輸出中不保留嵌套。 Unflatten 反轉該過程並重建嵌套結構。
扁平化時如何處理陣列?
使用其索引作為路徑段來扁平化陣列元素。 {"roles":["admin","editor"]} 成為 {"roles.0":"admin","roles.1":"editor"} 用點符號表示,或 {"roles[0]":"admin","roles[1]":"editor"} 在括號表示法中。索引保留順序,因此可以在您放平時重建數組。
我可以將虛線鍵拆回嵌套的 JSON 嗎? 是的。切換到非扁平模式並貼上一個扁平對象,其鍵是虛線路徑。該工具重建嵌套物件和數組,透過每個路徑段是否是整數索引來決定數組與物件。當分隔符號和數組符號匹配時,扁平和不扁平是精確的逆。
點數組符號和括號數組符號有什麼差別?
兩者編碼相同的數組索引;只是語法不同。寫點符號 items.0.id,它結構緊湊,常見於 config 和 i18n 鍵。括號表示法寫道 items[0].id,與 JavaScript 存取語法和某些查詢語言相符。選擇目標系統期望的任何一個,並對兩個方向使用相同的系統。
扁平化會遺失任何資料嗎? No。 標量、空值、布林值,甚至空物件和空數組都保留為葉值,因此取消壓縮結果會再現原始文件。需要注意的一件事是已經包含分隔符號的鍵,這就是分隔符號可配置的原因。
我為什麼要壓平 JSON? 展平使嵌套資料適應期望一級金鑰的系統:電子表格列、環境變數、點翻譯金鑰、特徵標誌儲存以及許多分析和日誌記錄管道。點路徑透過平面格式承載原始結構,因此不會遺失任何內容。
如果一個鍵已經包含一個點會發生什麼事? 鍵內的文字點與路徑分隔符號不明確,因此往返可能會將其分割到錯誤的位置。將分隔符號變更為未出現在鍵中的字元(例如斜線或管道),並對扁平和不扁平使用相同的分隔符號。
我的 json 上傳到任何地方了嗎？ 不。解析和轉換在瀏覽器中以 JavaScript 形式運行。沒有任何內容被傳輸、記錄或儲存。您可以透過在展平時查看網路標籤或離線來確認這一點,因為該工具在沒有連接的情況下繼續工作。
