6. json--注释

1. 前言

JSON 是一种纯粹的数据交换格式，其简单、灵活的特性使得 JSON 适合被用于各种不同的场景，例如在配置文件中、在接口返回的数据中都会用到 JSON 格式。然而 JSON 却有一个非常明显的缺点，那就是 JSON 不能像编程语言那样添加注释，JSON 中的任何内容都会看作数据的一部分。

之所以不允许添加注释，是因为 JSON 主要是用来存储数据的，过多的注释会对数据的可读性造成影响，同时也会造成数据体积变大，进而影响数据传输、解析的速度。

但是，在某些场景中，我们又需要使用注释。例如在 JSON 格式的配置文件中，我们希望以注释的形式对配置信息进行解释说明；在接口返回的 JSON 数据中，我们希望通过注释描述数据的含义等等。那么我们要怎么在 JSON 数据中添加注释呢？下面就来介绍几种方法。

2. 使用特殊的键名

想要在 JSON 中添加注释，我们可以在要添加注释键/值对的前面（或后面）添加一个同名的键，并在键名中添加一个特殊字符加以区分，例如@、#、?、_、/等，然后在与键对应的值中定义注释的内容。

注意：在键名中添加特殊字符时，应尽量避免:、{、}、[、]等 JSON 中常用的字符。

下面通过一个简单的示例来演示一下如何通过特殊的键名在 JSON 中添加注释：

 1 {
 2     "@name": "网站名称",
 3     "name": "百度网址",
 4     "_url": "网址",
 5     "url": "https://www.baidu.com/",
 6     "course": "JSON 教程",
 7     "@charge": "0=收费; 1=免费",
 8     "charge": 1,
 9     "#list": "教程目录",
10     "list": [
11         "JSON数据类型",
12         "JSON对象",
13         "JSON数组"
14     ],
15     "message": {
16         "code": 0,
17         "message": "OK",
18         "#data": {
19             "#id": "用户ID",
20             "#type": "0=正常; 1=异常",
21             "#name": "姓名",
22             "#createTime": "创建时间(yyyy-MM-dd)"
23         },
24         "data": {
25             "id": "12345",
26             "type": 0,
27             "name": "我的名字",
28             "createTime": "2022-05-20"
29         }
30     }
31 } 

除了可以在键名中添加特殊字符外，也可以直接以“comment”、“_comment” 或 “__comment”作为键名来定义注释，如下例所示：

1 {
2     "_comment": "这是注释，这是注释",
3     "course": {
4         "name": "JSON 教程",
5         "url": "https://www.baidu.com/"
6     }
7 }