YAML第一次正确烧录我,它是一个国家代码,我正在将一个Laravel项目中的区域设置配置's JSON文件移到一个部署友好的YAML格式,按我的去手转换,因为"it's只是将大括号改为缩进。"其中一个条目是挪威: "country": "NO"。在YAML中,未引用,那's不是字符串-在YAML 1.1规则下,PyYAML和许多其他解析器仍然适用, NO 是布尔值 false。 部署脚本是用 Python 编写的,愉快地将挪威用户评价为: country: false 并将它们路由到后备区域。这个错误有一个名字 - 社区称之为挪威问题 - 我必须以手工方式发现它,一次一张混乱的支持票。
JSON 手转换为 YAML 看起来微不足道,实际上是一个雷区,因为两种格式对于一个裸词的意思有着截然不同的想法,在 JSON 中,一切都是显性的:字符串有引号,数字 don't, true/false/null ares关键词,故事的结尾在YAML中,一个未引用的标量得到 解释: no 成假, 3000 成整数, 1.10 成为浮子 1.1 (再见, 版本字符串), 08 chokes一些解析器作为无效的八进制,一个带有杂散冒号空间的值在你最意想不到的时候变成嵌套映射,这些每一个都是静音数据损坏- 文件解析得很好,类型就是错误的。
甲 JSON 到 YAML 转换器 这会理解这些规则,让您获得可读性 YAML 是在没有轮盘赌类型的情况下发明的。我为 toolz。dev 构建的那个检测到每个模糊标量 - 布尔相似值、数字相似值、YAML 1.1 遗留值、具有特殊字符的字符串 - 并准确引用这些,因此在下一个工具解析 YAML 后,JSON 中的字符串仍然是一个字符串。那"正是那些"很重要:引用 一切 也会很安全,但输出看起来不再像惯用的 YAML,惯用语就是重点。
本指南涵盖了转换如何处理 YAML's 锐边、为什么 JSON 在技术上已经是 YAML(以及为什么这一事实对您没有帮助't),以及 Kubernetes、CI 和 Docker Compose 工作流程,其中此转换每周发生一次。
TL;博士: 将 JSON 粘贴到 Toolz.dev JSON 到 YAML 转换器、挑选2或4个空格缩进,并得到干净的块式YAML与类型安全报价-
"3000"保持一根绳子,"no"保持一根绳子,"1.10"stays a 版本。密钥顺序被保留, 空集合出来为[]並{}并且所有内容都运行客户端,因此配置秘密永远不会离开您的浏览器。与。往返 YAML 验证器并且首先使用 the 格式化源 json格式化程序。
Isn't JSON 已生效 YAML?
是的 - 并且它是 's 最无用的 "是的"在配置管理中。 YAML 1.2 被明确设计为 JSON 的超集:每个有效的 JSON 文档都解析为有效的 YAML。您可以将原始 JSON 粘贴到 Kubernetes 清单中 kubectl 会接受。
没有人这样做,因为 YAML 存在的原因是 人体人体工程学。Kubernetes 体现、GitHub Actions 工作流程、Docker Compose 文件、Ansible 剧本、家庭助理配置 - 这些都是 YAML,因为人们不断地阅读和手工编辑它们,并且 replicas: 3 在缩进块扫描下比 {"replicas":3} nested in braces。当有人说"将JSON转换为YAML时,"他们的意思是 块样式 YAML:缩进代替大括号, - dashes而不是括号内的数组,不需要任何引号的地方没有引号。
最后一个子句是困难所在。从 JSON's everything-explicit 语法到 YAML's 最小语法意味着 决定每个字符串是否可以安全地丢失其引号- 而这个决定需要比大多数人类在周五下午 5 点可靠地了解 YAML's 标量分辨率规则。那's 转换器的实际工作;大括号到缩进部分是微不足道的。
当你手动转换时,什么会悄然破碎?
失败案例分成四个家族,I've在真实配置中击中了每一个:
布尔人的长相相似。 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部署工具中。挪威问题(x),在你这个国家/地区,我们会发现,在你这个国家/地区,我们会发现,在你这个国家/地区,我们会发现,在你这个国家/地区,我们会发现,在你这个国家/地区,我们会发现,在你这个国家/地区,我们会发现NO → false)及其表弟安大略问题(ON → true)是这个家族'最热门的。
数长得像。 "port": "3000" 转换为 port: 3000 现在是一个整数。 Kubernetes 不't 在某些领域很关心,而在其他领域则很失败 - 例如,env var 值必须是字符串,并且 kubectl apply 将拒绝那里的整数,并出现一个错误,该错误命名了字段,但没有命名 为什么。版本字符串更糟糕,因为没有失败: version: 1.10 解析为浮动 1.1并且您的部署脚本会高兴地永远报告错误的版本。领先的零 - 邮政编码、电话号码、八进制 ID 喜欢 0755- 完善家庭。
特殊角色。 Colon 后面跟一个未引号值内部的空格,开始一个映射 (message: error: not found 是解析错误或嵌套地图,解析器取决于)。A # 开始评论中值。领先 *、 &、 ! YAML's锚、别名、标签语法相撞,带有换行的字符串需要转义或块标量。
的空字符串。 YAML 中未引用的空是 null不是 ""。任何持有空字符串的 JSON 字段都必须引用或更改类型。
的 转换器 检查所有四个系列的每个字符串并引用需要它的人 - 而且只有那些。 production 裸露出来,因为它's明确; "3000"、 "no"、 "1.10"、和 "" 出来引用是因为它们是't。那里's还有一个"引用所有字符串"切换当你're喂你不做的解析器't信任并希望发生零标量分辨率。
如何使用该工具将 JSON 转换为 YAML?
第 1 步:粘贴您的 JSON
任何有效的 JSON 都可以 - 对象、数组、深嵌套、 统一码。Load Sample 按钮为您提供一个逼真的服务配置,可以练习有趣的情况:数字字符串端口、布尔值、空数组、嵌套地图。如果您的输入有语法问题,转换器会报告解析器's的精确错误,而不是转换截断的文档;用于追捕 哪里 错误是在一个大斑点上, json格式化程序 是更好的显微镜。
2步:选择缩进
两个空格或四个。两个是压倒性的约定 - Kubernetes 文档、GitHub Actions 示例、Docker Compose 参考文献和 yamllint defaults 都使用它 - 但有些团队为了深度嵌套的可读性而对四个进行标准化。无论您选择哪个,转换器都对其保持一致,包括键下列表项的微妙情况,其中不一致的手缩进是 " 的经典来源。此处不允许映射值 " 错误。
3步:转换和审查
Line和字节计数时出现输出,略过一次- 不是为了正确性(that's转换器's工作)而是为了理智- 根据你的期望检查报价决定,看 PORT: "3000" 引用时 NODE_ENV: production isn't是告诉你哪些价值观是危险的工具。
4步:复制或下载
复制到剪贴板以粘贴到现有清单中,或下载为 a .yaml file。out仅使用空格- YAML禁止缩进的选项卡,这值得您以后在为选项卡缩进配置的编辑器中编辑文件时知道。
JSON vs YAML:每种格式何时获胜?
| JSON | 山药 | |
|---|---|---|
| 阅读/编辑 | 机器、API | 人类,行动小组 |
| 评论 | 规格中没有 | # 评论 - 配置的杀手级功能 |
| 类型显式 | 总计 - 报价决定一切 | 标量分辨率 - 上下文决定 |
| 多行字符串 | \n 仅逃脱 |
块标量(` |
| 解析速度&无处不在 | 到处都是最快的 | 解析器更慢、更重 |
| 脚枪 | 尾随逗号,that's 关于它 | 挪威问题、选项卡、缩进漂移、版本截断 |
| 自然栖息地 | API 有效负载, package.json,数据交换 |
Kubernetes、CI 管道、Compose、Ansible |
表格后面的模式:JSON 在机器写入和机器读取的地方获胜; YAML 在机器读取但 a 的任何地方获胜 人类 writes。configuration正好位于第二类,这就是为什么json到yaml方向是常见的 - 数据在API或数据库导出中开始生命,需要成为操作团队可以维护的东西。反向跳转,YAML回到机器可读的JSON,就是这样 YAML 验证器 手柄 - 粘贴 YAML,获得验证加上等效的 JSON。
此转换有哪些日常工作流程?
来自 API 输出的 Kubernetes 表现
kubectl get deployment my-app -o json give you JSON;你检查到 Git 中的清单是 YAML。将 API 响应转换为干净的 YAML 是从实时资源引导清单的最快方法 - 转换,剥离服务器填充 status 並 metadata.managedFields blocks,并且你有一个声明性的起点,类型安全的引用在这里赚取它的保留:kubernetes 中的 env 值 必须 be字符串,以及转换器's坚持报价 "3000" 是之间的区别 kubectl apply 成功与失败。
CI 管道配置
GitHub 操作和 GitLab CI 仅限 YAML 当 I'm 编程生成工作流步骤时 - 用于测试 WP 的 PHP 和 Node 版本矩阵 Adminify 对照,比如说 - 生成器自然产生 JSON,最后一步是转换测试矩阵中的版本字符串正是被朴素转换破坏的值:矩阵 ["1.9", "1.10", "1.11"] 手工转换,无需针对 PHP 进行报价测试 1.1 两次。的 编码工具集合 涵盖了更多生成然后转换模式。
Docker 从检查输出组成
docker inspect 发出JSON; docker-compose.yml wants YAML。reverse-engineering a Compose file from a runing container - ports, volumes, env - is a convert-and-prune job。empty arrays and objects convert to [] 並 {} flow 语法,Compose 接受并保持修剪阶段可读。
使配置可审查
Zhe一个被低估了:JSON配置几十个嵌套密钥在代码审核中很惨,部分原因是它们可以't携带注释。转换为YAML让你注释 为什么 rateLimit is 250 紧邻值 对于复习本身,将转换与 a 配对 结构差异 JSON 保留 " 之前/之后 " 实际上发生了什么变化 " 问题诚实,而 YAML 版本则处理 " 为什么。"
OpenAPI 和架构文档
OpenAPI 规范通常在 YAML 中编写,但生成并用作 JSON。将生成的规范转换为 YAML 进行人类编辑(然后验证往返 - 是标准的 API 团队工作流程,保真保证(保留密钥顺序,引用类型)意味着 YAML 版本与其 JSON 祖先保持差异。
为什么关键订单保存很重要?
JSON规范,对象键顺序没有任何意义- {"a":1,"b":2} 並 {"b":2,"a":1} 是同一个对象,所以一个转换器可以按字母顺序对密钥进行排序,并且在技术上是正确的,它实际上也是敌对的,因为配置文件是 读 依次为:kubernetes 部署自然读取为 apiVersion、 kind、 metadata、 spec- 按字母顺序排序这些内容会产生一个清单,该清单的解析方式相同,读起来像勒索信。
转换器按源顺序发出密钥。您的文档心理模型在转换中幸存下来,YAML 与之前相同源的转换以及传统排序(值之前的名称、 apiVersion 先)保持常规。如果你 想要 出于比较目的的规范排序,这'是一个困难的工具问题 - json 差异检查器 无论顺序如何,按键进行比较,这是该问题的正确层。
转换包含秘密的配置安全吗?
Configuration 是开发人员处理的最密集的文本 - 嵌入密码的数据库 URL,env 块中的 API 令牌,映射你的基础设施的内部主机名。It's 也正是人们粘贴到在线转换器中的内容,通常是在部署中期,通常是在匆忙中。
的 Toolz.dev 转换器 完全在您的浏览器中运行:解析、标量分析、序列化 - 所有这些都是客户端 JavaScript,没有网络请求携带您的数据,并且该工具不断处理您的连接剪切。that's 架构事实,而不是隐私政策承诺。整个工具箱背后的浏览器优先设计理念在。 web开发人员工具包指南;该工具是应用于工作流程中单一最敏感文档类型的理念。
显而易见的警告是:客户端转换可以保护 转换。之后粘贴输出的地方是它自己的安全决策。
常问问题
如何在线将JSON转换为YAML？
将您的 JSON 粘贴到 JSON 到 YAML 转换器、选择2或4个空格缩进,然后点击转换,你得到块式YAML,带有类型安全引用,可以复制或下载为。yaml文件转换完全在你的浏览器中运行- 没有上传任何内容。
JSON 已经有效 YAML 吗?
Technically yes - YAML 1.2 是 JSON 的超集,所以任何有效的 JSON 文档都解析为 YAML。但 JSON 语法击败了 YAML's 可读性目的。转换产生带有缩进而不是大括号的块式 YAML,这就是 Kubernetes 体现的,CI 工作流程和组成文件期望人类读取和编辑。
YAML中的挪威问题是什么?
YAML 1.1 标量规则下,像 PyYAML 这样的解析器仍然适用,未引用的值 no, yes, on, 和 off 解析为布尔值 - 因此国家代码 NO 默默地变为虚假转换器通过自动引用 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's可读性是真实的,它的锐边也是 - 格式从上下文解析类型,上下文正是手转换出错的地方 一个知道标量规则的转换器给你可读的配置,而不会出现静音类型损坏: 转换您的 JSON、略去它选择的引文,并在挪威仍然是一个国家的地方运送一份清单。
