开发者工具 · JSON 格式化程序和验证程序
为什么一致的 JSON 缩进可以让你的 git diff 可读
· 为什么它很重要
json 开发人员工作流程 验证
当两个工具对缩进不一致时，存储库中的每个 JSON 文件都会显示为已更改。这篇文章解释了为什么缩进一致性对于审查很重要，如何选择缩进一致性，以及如何安全地重新格式化。
更改了四百行，编辑了一个值
更改了 400 行，编辑了一个值 - 由于编辑器重新格式化了文件，因此没人可以审查该拉取请求。基于行的差异将缩进更改视为替换，因此预期的版本凹凸会在机械更改的行中消失。审阅者要么花时间过滤噪音，要么在没有自信地检查语义编辑的情况下批准。
ToolAcre 可以匹配两个、四个或八个空格或制表符，并且可以在有意选择时对键进行排序。它不保留原始行结尾，因为 JSON.stringify 会发出新文本。如果团队希望审核差异保持清晰易懂，则应将存储库范围的标准化与语义编辑分开。应在广泛重写之前选择格式化策略。
空格对于 JSON 来说无关紧要，但对于 diff 来说非常重要
空格对于 JSON 来说无关紧要，但对于 diff 来说非常重要 - 为什么缩进的更改会重写每一行。解析器忽略字符串外部的空格、制表符和换行符，但版本控制比较从文本行开始。将两个前导空格更改为四个会改变几乎每个嵌套行，即使生成的数据结构是相同的。
这种噪音的影响超出了美观。归咎历史转移到标准化提交，使用先前布局的分支上的合并冲突增加，并且代码审查失去了正常的信噪比。稳定的格式使单值编辑保持为一行更改。应用标准化一次，进行传达并避免将其与功能配置更改混合。存储库范围内的一致性还可以让审阅者立即识别意外的格式化程序输出，并保持自动更改摘要专注于实际配置行为更改。
两个空格、四个空格或制表符
两个空格、四个空格或制表符——常见生态系统的默认设置，以及为什么选择比坚持它更重要。两个空格可以使深度嵌套的文档变得更窄；四创造更强的视觉分离；选项卡允许显示宽度首选项，但与对齐方式和静默转换它们的工具交互效果不佳。
选择存储库中已占主导地位的约定，并将其编码在 Prettier、EditorConfig 或生成工具中，而不是依赖于内存。确保贡献者和 CI 使用兼容的版本。 JSON 语法接受每个选项，因此有关通用正确性的争论错过了操作点：确定性输出阻止编辑器、生成器和格式化程序轮流重写同一文件。固定格式化程序版本可以避免升级后的策略漂移。
行结尾和尾随换行符
行结尾和尾随换行符 — CRLF 与 LF 以及丢失的最终换行符作为整个文件差异的其他来源。当格式化程序发出 LF 时，为 CRLF 配置的签出可能会替换每一行。已解析的 JSON 未更改，但 Git 和审核界面可能会显示存储库范围内的文本重写。
通过存储库属性和格式化程序配置有意设置行结束策略，然后在贡献者使用的平台上验证它。保留习惯的最后换行符，这样命令行工具和差异就不会笨拙地报告最后一行。由于解析和重新序列化工具会生成新文本，因此在将生成的字节级约定应用于许多文件之前，请先对其进行比较。十六进制检查可以区分行结束改动和值更改。
工作示例：规范化存储库的 JSON
工作示例：规范化存储库的 JSON — 库存严格 JSON 文件，选择现有的两空格约定并在专用更改中重新格式化它们。排除其生产者拥有序列化和严格格式化程序无法解析的 JSON 类方言的生成工件。前后运行测试以验证消费者是否仍然读取相同的值。
在规范化窗口周围合并或变基活动功能分支以减少冲突，然后在 CI 中强制执行所选的格式化程序。规范化审查不应包含键排序或值编辑，从而更容易建立结构等效性。后续拉取请求可以在其发生的精确行上显示依赖项版本更新或标志更改。
仔细审查 JSON 变更
很好地审查 JSON 更改 - 在比较之前对两个版本进行相同的格式化，因此只有语义更改脱颖而出。检查数组是否改变了顺序、数字是否变成了字符串以及键是否消失而不是移动。引号和文字类型所具有的含义是仅靠缩进无法计算的。
避免对键进行排序，除非存储库明确将顺序视为不相关并期望规范排序。尽管对象成员顺序通常缺乏应用程序意义，但重新排序会扩大差异并可能影响保留插入顺序的工具。对于安全敏感的策略或清单，请将文本审查与模式验证和特定于消费者的检查结合起来，而不是仅仅因为格式化的差异很小而批准。
这不包括什么
这不包括键排序和语义差异，它们需要理解结构而不是线条的工具。两个文档在生成等效对象时可以进行不同的序列化，并且两个外观相同的值在应用程序模式下可能会产生不同的结果。格式使表示标准化，但不定义语义等效性。
它也不保证字节保存。重新序列化可以规范转义和数字拼写、更改行结尾以及舍入不安全的 JavaScript 整数。生成的文件可能需要精确的生产者版本，并且签名的文件不得随意重写。在应用存储库范围的格式化之前，确定工件是源数据、生成的输出还是规范的签名数据。
要点：一处缩进，尽早执行
要点：一次缩进，尽早强制执行 - 使用格式化程序的缩进设置来匹配项目，而不是强加个人偏好。同时对齐行尾和最终换行策略，然后自动化这些选择，以便每个编辑器和 CI 运行都能生成稳定的文本。一致性比任何特定宽度更能保护审阅质量。
如果需要规范化，请将其与语义工作隔离并将其公告到活动分支。在提交之前检查重新序列化的输出是否存在大整数、转义更改和不需要的键排序。一旦基线稳定，普通的 JSON 更改就会保持狭窄，指责仍然有用，审阅者可以专注于价值观和结构，而不是从格式化噪音中重建意图。