信息技术数字 » 程序设计 » 如何向 JSON 文件添加注释：方法、示例和最佳实践
JSON 不允许本机注释；解决方法包括自定义键或预处理器。
使用非标准注释可能会带来兼容性风险或信息丢失。
外部文档或仅在开发中使用 JSONC 是更安全的选择。
使用 JSON 文件 它是任何开发软件、Web 应用程序或管理现代配置的人的日常工作。然而，像在文件中添加解释性注释这样常见的事情可能会变成一场真正的噩梦，因为 JSON 格式本身就…… 不允许正式发表评论许多人想知道如何才能记录结构或阐明数据的特定部分而不导致分析错误或不良做法。
通过本文您将了解 为什么 JSON 不允许注释，以及目前可用的最佳替代方案（当然，开发人员总能找到绕过限制的方法）以及每种方法的含义。您还将了解如何避免兼容性问题，以及如果您需要注释 JSON 文件以进行协作或了解未来的更改，最智能的解决方案。
为什么 JSON 本身不支持注释？
在我们深入研究技巧和解决方法之前，了解问题的根本原因非常重要。 JSON（JavaScript对象表示法） 它诞生于一种用于在系统间交换数据的简单而高效的格式。它的主要优点正是这种简单性：它仅支持对象、数组、字符串、数字、布尔值和空值等数据结构。 没有为元信息或其他编程语言中非常有用的解释性注释保留空间。.
这种限制并不是疏忽，而是一个 深思熟虑的设计决策 该格式的创建者和主要推动者道格拉斯·克罗克福德 (Douglas Crockford) 拍摄。他解释说，他从规范中删除了注释，因为许多人利用这些注释引入解析指令，而这些指令最终可能会导致不同应用程序之间不兼容或妨碍自动处理。 这个想法是让 JSON 尽可能的通用和可预测。，为了互操作性而牺牲内部文档等方面。
如果你曾经尝试过使用典型的评论 // comentario, /* comentario */ Øincluso # comentario 在 Python 或 Bash 风格的 JSON 文件中，您可能会遇到错误“JSON 中不允许注释”甚至不可能通过一些简单的技巧来绕过限制：标准解析器将拒绝读取内容不完全符合格式的文件。
JSON 中缺少注释会导致什么问题？
无法添加评论会产生实际后果，影响从个人项目到大型企业应用程序开发的一切：
JSON 文件本身的文档不存在这使得我们很难理解每个键的功能或某些值的原因，尤其是随着时间的推移或不同的人使用同一个文件时。
修改、扩展或修订 必须在无法直接在文件中证明更改的情况下进行更改，这可能会导致协作项目的混乱。
由于遗忘或解释而导致的错误更有可能发生因为没有人能够在线解释每个部分的作用或复杂结构背后的逻辑是什么。
Turbo Pascal - 历史和版本由于没有官方的方式来插入评论， 社区已经开发出不同的策略和技巧 记录（即使间接地）JSON 的内容。
解决方法：如何在 JSON 文件中包含注释
尽管规范 禁止以通常的风格发表评论记录 JSON 文件的方法有很多种。每种方法都有其优点、局限性和风险，因此在决定使用哪种方法之前，了解它们非常重要。
1. 添加注释专用键（最常见的解决方案）
毫无疑问， 最广泛和最简单的技术是添加键值对，其目的是作为注释。经常使用不太可能的代号，例如 _comentario o __nota__，它们不会与“真实”数据的任何键冲突。
基本示例：
{ "_comment": "这是应用程序 X 的配置文件", "user": "JohnDoe", "permissions": , "active": true }
目标是 使用 JSON 的应用程序忽略这些键或者开发人员立即将它们识别为注释而不是与操作相关的信息。
优点：
允许您在文件本身内的每个需要解释的字段旁边添加解释。
与任何遵循 JSON 标准的工具兼容（只要它忽略它无法识别的键）。
缺点：
这些“注释”将成为数据的一部分。如果文件用于公共 API 或对大小有要求的生产环境中，则此方法可以 不必要地增加负载的重量.
作为一次非正式会议， 如果将来 JSON 模式确实需要同名的键，则可能会出现问题。.
如果出现这些意外的输入，任何仅需要某些键的解析器都可能失败。
2. JSON 的非官方变体：JSONC
另一个在开发人员中越来越流行的选择是使用 JSONC （带注释的 JSON），一种非官方格式，允许使用以下方式包含注释 // y /*...*/。 但是， 这些 JSONC 文件需要预处理器：在将文件传递给任何标准解析器之前删除注释的工具。
JSONC 示例：
{ // 应用管理员用户 "user": "admin", /* 高级权限设置 */ "permissions": }
要使用 JSONC，您可以在开发过程中找到支持此格式的在线工具、Node.js 软件包或 Visual Studio Code 等编辑器扩展。当您的文件准备好投入生产后， 预处理器删除注释并生成有效的 JSON.
优点： 在您开发时方便记录，而不会污染最终数据。
缺点： 此方法仅在开发阶段有效。如果您在使用前忘记处理文件，解析器将会报错。
3. 外部文档：最安全的选择
对于必须严格遵守 JSON 标准的项目，最安全的建议是 将文档保存在档案库之外您可以通过创建 Markdown 或纯文本文件来实现这一点，在其中解释结构、每个字段的用途以及任何相关细节。如果您要定义 API，也可以使用项目 Wiki 中的文档或 Swagger/OpenAPI 等工具。
Laravel 中的 Blade 指令 hasStack 和高级堆栈控制优点：
没有办法破坏解析器兼容性或增加数据大小。
避免名称冲突并保持 JSON 文件清洁并专注于数据。
缺点：
文档是分离的。如果有人编辑 JSON 而不更新外部文档，这可能会导致缺乏协调。
对于小型项目或喜欢在一个地方找到所有信息的人来说，它不太实用。
4. 预处理器和构建工具
扩展 JSONC 策略，在大型项目中经常使用它们 自定义预处理器，允许您添加注释或特殊指令 在配置文件中。这些工具集成到应用程序构建过程中，负责在将产品部署到生产环境之前清理所有注释。
这种方法 将内部文档的便利性与符合标准的安全性结合起来，但它需要更复杂的工作流程和注意力，以避免意外上传原始文件。
高级示例：复杂 JSON 结构中的注释
案例研究展示了如何利用约定来记录 JSON 文件，即使存在嵌套对象或数组。
带有几条不同评论的示例：
{ "_comment1": "个人信息", "name": "Ana", "age": 28, "city": "Madrid", "_comment2": "职位信息", "company": "InnovaSoft", "position": "开发人员", "experience": 5 }
如果需要在嵌套对象内添加注释：
{ "name": "Luis", "_comment": "附加信息", "additionaldata": { "email": "luis@email.com", "_comment": "此电子邮件必须由用户验证" } }
请记住： JSON 不允许在同一对象级别使用重复的键，因此如果您需要添加多个注释，则必须为它们指定唯一的名称，例如 _comentario1, _comentario2等等。
记录 JSON 文件时的含义和注意事项
使用上述任何一种方法都会有副作用。 在做出最终决定之前需要考虑的是：
注释键占用空间并传输到后端、API 或任何使用 JSON 的系统。如果效率至关重要，最好避免超载。
某些方案（例如公共 API 合同）可能会拒绝带有意外密钥的文件。在添加此类评论之前，请务必查阅该服务的官方文档。
如果项目发展，有一天您需要使用已经用作注释的密钥，则可能会出现不兼容的情况。. 尝试选择不寻常的名称以最大程度地降低风险。
一些 JSON 解析器允许存在未知键，而另一些则不允许。 可移植性可能会受到您使用的语言或库的影响。.
与其他数据格式的区别：YAML 和 XML
您可能想知道为什么 YAML 或 XML 等广泛使用的格式允许注释而 JSON 却不允许。 答案在于每种格式的方法.
Yaml 它以可读性以及允许在前面添加注释而出名 # 文件中的任何地方。而 XML 则使用标签 插入将被解析器忽略的解释。
正如我们所见，JSON 优先考虑通用性和最小复杂性，消除任何不属于数据的元素； 因此它在效率、速度和兼容性至关重要的 API、配置和环境中很受欢迎。.
使用非标准方法有哪些风险？
实施替代解决方案并非没有风险。最重要的是：
数据丢失- 如果未来版本对任何注释键进行标准化，您可能会丢失信息或在您的应用程序中产生冲突。
困惑和误解：其他开发人员可能不熟悉您的约定，并认为注释键是真实数据。
分析中的错误- 如果您的 JSON 到达需要严格模式的系统，则包含不受支持的字段可能会导致文件被拒绝或静默失败。
Visual Studio Code：你需要了解的关于最通用编辑器的一切关于 JSON 注释的关键问题
有没有在 JSON 中添加注释的官方方法？ 不可以，规范不允许。
为什么没有官方支持？ 尽可能保持 JSON 简单、快速、兼容。
我有什么选择？ 为注释添加自定义键，在开发期间使用预处理器，或在外部文件中维护文档。
以非标准方式添加评论是否存在风险？ 是的，特别是在兼容性、数据混乱和潜在的信息丢失方面。
我可以在生产中使用 JSONC 吗？ 不推荐。它只能在开发环境中与预处理器结合使用，以便在部署之前清理注释。
如果我注释的 JSON 文件到达外部 API 会发生什么？ 您很可能会收到错误并且文件将被拒绝。
记录 JSON 文件的建议和最佳实践
根据项目的环境和要求，您可以选择最适合您需求的方案。一些有用的指导原则：
在开发中，如果有帮助的话，使用注释键或 JSONC。但不要忘记在将文件发布到生产环境之前清理它们。
对于长期或合作项目，请选择外部文档。：它是最安全、可扩展和通用的选择。
如果必须在文件中包含注释，请使用清晰的约定和不会冲突的键名。如 __nota_privada_dev__ 或类似。
始终检查与将使用 JSON 文件的工具、API 或外部系统的兼容性。.
本质上，使用 JSON 意味着接受它的规则：没有官方评论，但总有创造的空间。如果您需要为自己或同事留下注释，请选择侵入性最低的选项，妥善记录您的约定，并始终关注未来的兼容性。虽然无法在文件中留下说明令人烦恼，但这正是 JSON 极简设计的挑战和价值所在。
相关文章：数据库类型：关系型数据库、NoSQL 数据库等
目录
为什么 JSON 本身不支持注释？JSON 中缺少注释会导致什么问题？解决方法：如何在 JSON 文件中包含注释1. 添加注释专用键（最常见的解决方案）2. JSON 的非官方变体：JSONC3. 外部文档：最安全的选择4. 预处理器和构建工具高级示例：复杂 JSON 结构中的注释记录 JSON 文件时的含义和注意事项与其他数据格式的区别：YAML 和 XML使用非标准方法有哪些风险？关于 JSON 注释的关键问题记录 JSON 文件的建议和最佳实践