第一次 YAML 正確地燒毀我時,它是一個國家/地區代碼。我正在將 Laravel 專案中的區域設定移出'將 JSON 檔案轉換為適合部署的 YAML 格式,一路上手動轉換,因為 "it'只是將大括號更改為縮排。"其中一個條目是挪威: "country": "NO". 在 YAML 中,未引用,即 '不是字串 - 根據 PyYAML 和許多其他解析器仍然適用的 YAML 1.1 規則, NO 是布林值 false。 用 Python 編寫的部署腳本愉快地評價了挪威用戶 country: false 並將他們路由到後備地點。這個錯誤有一個名字--社區稱之為挪威問題--我以手工方式發現了它,一次一張混亂的支持票。
將 JSON 手動轉換為 YAML 看起來微不足道,實際上是一個雷區,因為兩種格式對於裸詞的含義有著截然不同的想法。在 JSON 中,一切都是明確的:字串有引號,數字 don't, true/false/null 是關鍵字,故事的結尾。在 YAML 中,得到一個未引用的標量 解釋: no 變得虛假, 3000 變成一個整數, 1.10 成為浮標 1.1 (再見,版本字串), 08 將一些解析器作為無效八進位進行阻塞,並且當您最意想不到的時候,具有雜散冒號空間的值就會變成嵌套映射。其中每一個都是靜默資料損壞 - 檔案解析得很好,類型是錯誤的。
一個 JSON 到 YAML 轉換器 了解這些規則可以讓您了解 YAML 的可讀性,而 YAML 是為無需輪盤賭類型而發明的。我為toolz。dev 構建的那個可以檢測每個不明確的標量- 布林相似值、數字相似值、YAML 1.1 舊值、帶有特殊字符的字串- 並精確地引用這些,所以JSON 中的字串仍然是下一個工具解析 YAML 後的一個字串。那個&引用;正是那些&引用;事項:引用 一切 也很安全,但輸出看起來不再像慣用的 YAML,而慣用才是重點。
本指南介紹了轉換如何處理 YAML'鋒利的邊緣,為什麼 JSON 在技術上已經是 YAML(以及為什麼這一事實對您沒有幫助),以及 Kubernetes、CI 和 Docker Compose 工作流程,每週都會進行這種轉換。
TL;DR: 將 JSON 貼到 toolz。dev JSON 到 YAML 轉換器,選擇 2 或 4 空間縮進,並透過類型安全引用取得乾淨的區塊式 YAML -
"3000"保持字串,"no"保持字串,"1.10"保留一個版本。保留關鍵訂單,空集合顯示為[]和{},一切都運行客戶端,因此配置秘密永遠不會離開您的瀏覽器。往返 yaml 驗證器,並先用 格式化來源 json 格式化程式.
Isn't JSON 已經有效 YAML 了嗎?
是的 - '是最無用的&引用;是&引用;在配置管理中。 YAML 1.2 被明確設計為 JSON 的超集:每個有效的 JSON 文件都解析為有效的 YAML。您可以將原始 JSON 貼上到 Kubernetes 清單中 kubectl 會接受它。
沒有人這樣做,因為 YAML 存在的原因是 人體工學。 Kubernetes 清單、GitHub 動作工作流程、Docker Compose 檔案、Ansible 劇本、Home Assistant 配置 - 這些是 YAML,因為人們不斷閱讀和手動編輯它們,並且 replicas: 3 在縮排塊下掃描效果更好 {"replicas":3} 嵌套在大括號中。當有人說"將 JSON 轉換為 YAML,"他們的意思是 塊式 YAML:縮排而不是大括號, - 破折號而不是括號數組,無需引用。
最後一個子句就是困難所在。從 JSON's 一切顯式語法到 YAML's 最小語法意味著 決定每個字串是否可以安全地遺失其引號- 這個決定需要了解 YAML'標量解析度規則比大多數人週五下午 5 點可靠地執行的規則更好。那'轉換器的實際工作;大括號縮排部分很簡單。
當你手轉換時,什麼會悄悄破裂?
故障案例分為四個系列,I'已在真實配置中擊中每一個:
布林相似。 YAML 1.1 解析 yes, no, on, off, y, n (在各種外殼中)作為布林值,YAML 1.2 保留 true/false. PyYAML - 仍然是大多數 Python 程式碼庫中的預設 YAML 庫 - 實作 1.1。所以 "debug": "no" 手工轉換為 debug: no 成為 debug: false 在您的 Python 部署工具中。挪威問題(NO → false)及其表親安大略問題(ON → true) 是這個家庭'最熱門。
數字相似。 "port": "3000" 轉換為 port: 3000 現在是一個整數。 Kubernetes 沒有'在某些領域關心,而在其他領域則遭遇失敗 - 例如,env var 值必須是字串,並且 kubectl apply 將拒絕一個整數,並帶有一個錯誤,該錯誤命名了該字段,但沒有命名該字段 為什麼。 版本字串更差,因為沒有任何失敗: version: 1.10 解析為浮點數 1.1,您的部署腳本很高興地永遠報告錯誤的版本。前導零 - 郵遞區號、電話號碼、八進位 ID 等 0755- 完善家庭。
特殊人物。 冒號後面跟著一個未引號值內的空格開始映射 (message: error: not found 是解析錯誤或嵌套映射,取決於解析器)。 A # 開始評論中值。領先的 *, &, ! 與 YAML 和#39 衝突;錨、別名和標籤語法。帶有換行符的字串需要轉義或區塊標量。
空字串。 YAML 中未引用的空性是 null,不 "". 任何持有空字串的 JSON 欄位都必須引用或變更類型。
的 轉換器 檢查所有四個系列的每個字串,並引用需要它的人 - 並且僅引用那些。 production 赤裸裸地出來,因為它's明確; "3000", "no", "1.10", 和 "" 出來引用是因為它們是't。那裡'還有一個&引用;引用所有字串&引用;切換何時'正在提供您不知道的解析器'信任並希望零標量解析度發生。
如何使用工具將 JSON 轉換為 YAML?
第 1 步:貼上您的 JSON
任何有效的 JSON 都可以工作 - 物件、陣列、深度嵌套、 統一碼。 Load Sample 按鈕為您提供真實的服務配置,用於練習有趣的情況:數字字串連接埠、布林值、空數組、嵌套映射。如果您的輸入有語法問題,轉換器會報告解析器'出現精確錯誤,而不是轉換截斷的文件;用於追捕 在哪裡 錯誤在於一個大斑點,the json 格式化程式 是更好的顯微鏡嗎。
第 2 步:選擇縮排
兩個空間或四個。兩個是壓倒性的約定 - Kubernetes 文件、GitHub 操作範例、Docker Compose 參考資料和 yamllint 預設情況下,所有團隊都會使用它 - 但有些團隊會標準化四個,以提高深度嵌套的可讀性。無論您選擇哪一個,轉換器都是一致的,包括鍵下列表項目的微妙情況,其中不一致的手動縮排是 " 的經典來源;此處不允許映射值"錯誤。
第三步:轉換和審查
輸出顯示行數和位元組數。撇去一次 - 不是為了正確性(即'轉換器和#39;工作),而是為了理智--根據您的期望檢查報價決定。看 PORT: "3000" 引用同時 NODE_ENV: production isn't 是告訴您哪些價值觀是危險的工具。
第四步:複製或下載
複製到剪貼簿以貼上到現有清單中,或下載為 .yaml 文件。輸出僅使用空格 - YAML 禁止選項卡縮進,當您稍後在配置為選項卡縮排的編輯器中編輯文件時,這一點值得了解。
JSON vs YAML:每種格式何時獲勝?
| 傑森 | 亞姆爾 | |
|---|---|---|
| 閱讀/編輯 | 機器、api | 人類、行動小組 |
| 評論 | 不在規格中 | # 評論 - 配置的殺手級功能 |
| 類型明確性 | 總計 - 報價決定一切 | 標量解析 - 上下文決定 |
| 多行字串 | \n 僅逃脫 |
塊標量(` |
| 解析速度&放大器;無所不在 | 最快,無所不在 | 速度較慢、較重的解析器 |
| 腳槍 | 尾隨逗號,即 's 關於它 | 挪威問題、選項卡、縮排漂移、版本截斷 |
| 自然棲息地 | API 有效負載, package.json,資料交換 |
Kubernetes、CI 管道、Compose、Ansible |
表後面的模式:機器寫入和機器讀取的任何地方 JSON 都會獲勝;只要機器讀取,YAML 就會獲勝 人類 寫。配置完全屬於第二類,這就是為什麼 JSON 到 YAML 的方向是常見的 - 資料在 API 或資料庫匯出中開始生命週期,需要成為操作團隊可以維護的東西。反向行程,YAML 回到機器可讀的 JSON,就是這樣 yaml 驗證器 手柄 - 貼上 YAML,取得驗證加上等效的 JSON。
此轉換的日常工作流程是什麼?
Kubernetes 源自 API 輸出
kubectl get deployment my-app -o json 給你 JSON;您檢查到 Git 的清單是 YAML。將 API 回應轉換為乾淨的 YAML 是從即時資源引導清單的最快方法 - 轉換、剝離伺服器填充 status 和 metadata.managedFields 塊,你有一個聲明性的起點。類型安全報價在這裡贏得了保留:kubernetes 中的 env 值 必須的 是字串,以及轉換器'堅持引用 "3000" 是之間的區別 kubectl apply 成功和失敗。
CI 管道配置
GitHub Actions 和 GitLab CI 僅適用於 YAML。當 I'm 以程式設計方式產生工作流程步驟 - PHP 和 Node 版本的矩陣,用於測試 WP Adminify,例如 - 生成器自然產生 JSON,最後一步是轉換。測試矩陣中的版本字串正是被樸素轉換損壞的值: 的矩陣 ["1.9", "1.10", "1.11"] 手動轉換,無引號測試針對 PHP 1.1 兩次。這 編碼工具集合 涵蓋了更多這種生成然後轉換的模式。
Docker 由 Inspect Output 組成
docker inspect 發射 JSON; docker-compose.yml 想要 YAML。從正在運行的容器(連接埠、磁碟區、環境)逆向工程 Compose 檔案是一項轉換和修剪工作。空數組和物件轉換為 [] 和 {} compose 接受並保持修剪階段可讀的流程語法。
使配置可審查
這個被低估了:具有數十個嵌套金鑰的 JSON 配置在程式碼審查中很糟糕,部分原因是它們可以't 攜帶註解。轉換為 YAML 可讓您進行註釋 為什麼 rateLimit 值旁邊是 250。對於評論本身,將轉換與 a 配對 結構差異 JSON 之前/之後保留 "實際改變了什麼"當 YAML 版本處理 "why。" 時,問題誠實
OpenAPI 和架構文件
OpenAPI 規範通常用 YAML 編寫,但產生並用作 JSON。將產生的規範轉換為 YAML 進行人工編輯 - 然後驗證往返 - 是標準 API 團隊工作流程,保真度保證(保留關鍵順序、引用類型)意味著 YAML 版本對其 JSON 祖先保持可差異。
為什麼關鍵訂單保存很重要?
根據 JSON 規範,物件鍵順序沒有任何意義 - {"a":1,"b":2} 和 {"b":2,"a":1} 是同一個物件。因此轉換器可以按字母順序對按鍵進行排序並且在技術上是正確的。它實際上也是敵對的,因為設定檔是 讀 按順序:kubernetes 部署自然讀作: apiVersion, kind, metadata, spec- 按字母順序對這些內容進行排序會產生一個清單,該清單的解析方式相同,讀起來就像贖金票據一樣。
轉換器按來源順序發出按鍵。文件的心理模型在轉換後仍然存在,YAML 與先前相同來源的轉換和傳統順序(值前名稱)完全不同 apiVersion 首先)保持傳統。如果你 想要 用於比較目的的規範排序,that'是一個不同的工具問題 - json 差異檢查器 無論順序如何,按鍵進行比較,這是解決該問題的正確層。
轉換包含秘密的配置安全嗎?
配置是開發人員處理的最秘密的文字 - 嵌入密碼的資料庫 URL、環境區塊中的 API 令牌、映射基礎設施的內部主機名稱。它'這也正是人們貼到線上轉換器中的內容,通常是在部署中期,通常是匆忙的。
的 toolz。dev 轉換器 完全在瀏覽器中運行:解析、標量分析、序列化 - 所有這些都是客戶端 JavaScript,沒有網路請求攜帶您的數據,並且該工具可以繼續處理您的連線中斷。 That'這是架構事實,而不是隱私權政策承諾。整個工具箱背後的瀏覽器優先設計理念在 中列出 web 開發人員工具包指南;這個工具的概念適用於工作流程中最敏感的單一文件類型。
顯而易見的警告是:客戶端轉換可以保護 轉換. 之後貼上輸出的地方是其自身的安全決策。
問號
如何在線將 json 轉換為 yaml？
將您的 JSON 貼到 JSON 到 Yaml 轉換器,選擇 2 或 4 空間縮進,然後按一下「轉換」。您將獲得具有類型安全引用的區塊式 YAML,可作為 。yaml 檔案複製或下載。轉換完全在您的瀏覽器中運行 - 不會上傳任何內容。
JSON 已經有效 YAML 了嗎?
從技術上講,是的 - YAML 1.2 是 JSON 的超集,因此任何有效的 JSON 文件都解析為 YAML。但 JSON 語法破壞了 YAML'的可讀性目的。轉換會產生帶有縮排而不是大寫的區塊式 YAML,這就是 Kubernetes 體現的 CI 工作流程和 Compose 文件期望人類讀取和編輯的內容。
YAML 中的挪威問題是什麼?
在 YAML 1.1 標量規則下(PyYAML 等解析器仍然適用),未引用的值 no、yes、on 和 off 解析為布林值 - 因此國家/地區代碼 NO 默默地變為 false。轉換器透過自動引用 YAML 解析器可以解釋為布林值、數字或空值的任何字串來防止這種情況發生。
數字字串會像 "3000" 轉換後保留字串?
是的。轉換器偵測到看起來像數字的字串並在輸出中引用它們,因此 "3000"保留一個字串而不是成為整數 3000。這對於連接埠、版本號(如 "1.10")很重要。 (否則會截斷為浮點 1.1)、郵遞區號和帶有前導零的 ID。
轉換器是否保留我的 JSON 金鑰的順序？
是的。按鍵按照來源 JSON 中出現的順序發出。排序鍵在技術上是有效的 - JSON 物件順序沒有任何意義 RFC 8259- 但來源順序使配置在其傳統結構中保持可讀性,並使 YAML 與其 JSON 來源保持可差異。
我可以直接在 Kubernetes 或 Docker Compose 中使用輸出嗎?
是的。輸出是標準區塊式 YAML,縮排有空格(從不帶選項卡),kubectl、Docker Compose、GitHub Actions 和 GitLab CI 都接受這些空格。必須是字串的值(如 Kubernetes env var 值)會被引用,從而避免 kubectl 在未引用的數字上引起的類型錯誤。
如何將 YAML 轉換回 JSON?
使用 yaml 驗證器 在 toolz。dev 上 - 它解析您的 YAML,報告任何語法錯誤,並輸出等效的 JSON。與 JSON 到 YAML 轉換器一起,它為您提供兩種格式之間的完整往返。
轉換包含秘密的設定檔安全嗎?
是的。轉換完全在瀏覽器中以 JavaScript 運行 - 沒有網路請求攜帶您的數據,沒有任何內容被儲存或記錄,並且該工具離線工作。使用資料庫憑證、API 令牌或內部主機名稱進行配置永遠不會離開您的電腦。
YAML'可讀性是真實的,它的鋒利邊緣也是真實的 - 格式從上下文中解析類型,而上下文正是手動轉換出錯的地方。知道標量規則的轉換器可以為您提供可讀配置,而不會出現靜音類型損壞: 轉換您的 JSON,瀏覽它選擇的引文,然後運送一份挪威仍然是一個國家的清單。
