附加包小册 §02：认识 JSON

上文中提到，JSON 文件是 Minecraft 的附加包的核心，因此我们必须要了解 JSON 的基本语法。

那么 JSON 到底是什么？

为什么要有 JSON

作为碳基生物（如果你不是来爬取本书内容的爬虫的话）的我们，在日常生活中，一般使用中文或者英文等语言进行交流——但这在计算机上行不通，因为除了 AI 大模型之外，计算机并不理解我们日常所使用的语言。

在这种情况下，我们就需要有一门「通用语言」来帮助人与计算机之间、计算机与计算机之间进行信息交换，例如下面一段自然语言写成的文本：

我有一只猫，它叫方漓，今年 3 岁，它喜欢吃鱼。

假如我们直接将这段文本「喂给」计算机，它会一脸懵，然而，如果我们将其转化为计算机所能理解的「通用语言」，例如 JSON，计算机就能理解了：

{
  "name": "方漓",
  "age": 3,
  "food": "鱼"
}

总而言之，JSON 是一种轻量级的文本数据交换格式，非常适合作为 Minecraft 附加包的配置文件格式，那么，JSON 的基本语法又是怎样的呢？

对象

{}

如上，对象用一对花括号表示，对象是无序的。

代码范例中的花括号是 JSON 中的根对象，根对象就如同一个「信息包」一样，把要交换的所有信息装在一起。

在附加包中，大部分 JSON 文件以根对象为基础，并向里面添加键值对。

字符串

"字符串"

字符串用英文双引号包裹，如果字符串内包含双引号，字符串内的双引号前需要加上转义符\。

布尔值

{
  "值1": true,
  "值2": false
}

布尔值只可以填true和false，其中true代表真，false代表假。

如上面的范例，值1被判定为真，值2被判定为假。

键值对

"键": "值"

上面所展示的键值对，每个键值对由一个、一个冒号、和一个值组成。

冒号相当于数学中的等号，连接键和具体内容，键值对中键必须是字符串类型，而值可以是任意类型，甚至是对象类型！

1 2	"键1": "值1", // 末尾有逗号 "键2": "值2" // 末尾没有逗号

若键值对后无键值对，则末尾不可以加逗号；若键值对后仍有键值对，则必须在末尾加逗号。

{
  "键1": "值1",
  "键2": "值2"
}

一般而言，键值对需要添加到对象中，如范例中的键值对被添加到了根对象中。

数组

1	"数组": ["值1","值2","值3"]

数组用中括号表示，里面的每一个数字称之为元素，元素除了数字外，还可以是字符串、布尔值、对象等类型。

与键值对类似，若元素后元素，则末尾不可以加逗号；若元素后仍有元素，则必须在末尾加逗号。

注释

// 行注释
/*
 123456
 块注释
*/

//是行注释，它之后所有的字符直到行尾都会被视为注释内容，不会被解析器识别。

/* */是块注释，这两个符号之间的所有内容都会被视为注释，从而被编译器忽略。

JSON 本身并不支持注释，但 Minecraft 为其提供了支持

常见错误

JSON 的语法非常严格，初学者经常会犯一些语法错误，导致其内容无法正常在游戏中运行。

尾随或缺失逗号

{
  "键1": "值1" // 末尾缺失逗号
  "键2": "值2", // 末尾有多余的逗号
}

若键值对后无键值对，则末尾不可以加逗号；若键值对后仍有键值对，则必须在末尾加逗号。

上面的范例中键1缺失了逗号；键2尾随了逗号。

使用全角符号

｛
  “值1”： true，
  “值2”： false
｝

除了字符串内的字符，JSON 中的符号必须是半角（英文）符号，否则就会出现错误！

缺少闭合符号

1
2
3

{
  "name": "Ivy",
  "age": 29  // 缺少右大括号 }

JSON 中的符号必须成对出现，否则编译器无法正确解析文件内容，正确写法如下：

{
  "name": "Ivy",
  "age": 29
}

排查错误

我们可以根据编译器的错误信息排查问题，同时你也可以通过 JSON 格式化工具来排查错误，以下是一些在线的 JSON 格式化/语法检查工具：