3 分钟了解 JSON Schema

大家好,我不是鱼皮。

幸运又不幸,我是一名程序员,他也是一名程序员。

周末,我在开发网站,他在开发游戏,两个人一起写代码,一起写 Bug 头秃,竟也有了一丝别样的浪漫,好不自在!

3 分钟了解 JSON Schema

今天,他遇到了一个后台的 Bug,游戏死活启动不了,我来帮忙排查一下,顺便给大家分享点编程小知识~

3 分钟了解 JSON Schema

Bug 起因

在开始游戏时,首先要加载一些配置,比如玩家的用户名、关卡的难度、玩家的初始道具等。

由于游戏是使用 Java 语言开发的,他把这些配置封装成了一个对象,代码如下:

// 游戏配置
class GameConfig {
// 玩家名
String name;
// 游戏难度
int difficulty;
// 玩家物品
String[] items;
}

为了开发调试方便,他写了一个默认的配置;并且为了方便管理默认配置,把它单独存放到了一个 JSON 格式的文件中,而不是写死在代码里。

默认 JSON 配置文件如下:

{
"name": "yupi",
"difficulty": 5,
"items": ["一级头", "二级甲"]
}

然后在程序中,读取该配置文件中的 JSON 字符串,再通过 Gson 解析库将 JSON 字符串转换为 Java 对象,就能获取到游戏配置信息,从而进行下一步处理了。

逻辑代码如下:

// 加载游戏配置
void loadConfig() {
String jsonStr = loadFile('config.json');
GameConfig config = new Gson()
.fromJson(jsonStr, GameConfig.class);
// 获取玩家名称
String name = config.getName();
// 更多处理
...
}

整个流程看起来非常简单,为啥会报错呢?

打印出异常信息,很明显,是 JSON 解析错误了:

3 分钟了解 JSON Schema

仔细一看,哎,这小糊涂,配置文件竟然输错了,行尾少了个必要的引号,当然会解析失败了!

{
// 行尾都少了个引号
"items": ["一级头", "二级甲]
}

他表示很无奈,没办法,开发的时候配置越堆越多、改来改去,一不注意就少打个字符了。

我笑到:JSON 格式确实是很灵活强大的,我们在工作中,也经常会编写一些复杂的嵌套 JSON。我倒是知道一个办法,可以帮助减少 JSON 文件写错的概率。

他不以为然:哦,什么办法?用编辑器或者校验网站检查一下?

3 分钟了解 JSON Schema

我:那也只能检查基本的语法吧,来来来,给你个更好康的神器 —— JSON Schema!

JSON Schema

JSON 格式的优点之一就是轻量,其本身并不支持写注释,所以没办法直接在文件本身中对字段进行描述。

因此,假如我们用 JSON 来做配置文件,大多数情况下都要对着文档来查看每个字段的类型、限制范围,才能编写出正确的配置。这样做不仅效率低,而且必须要自己来校验编写出的配置是否正确,一不小心就写错了。

而 JSON Schema 就是为解决此问题而生的,他本身就是 JSON 文件,用来注解和校验 JSON 文件。

举个例子,上面的游戏配置中,因为不小心输错了字符串数组导致程序出了 Bug。那可以编写一个 JSON Schema 来校验 items 字段是否为合法数组,代码如下:

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://www.code-nav.cn/latest.json",
"title": "GameConfig",
"description": "游戏配置",
"type": "object",
"properties": {
"items": {
"type": "array"
}
}
}

在这个文件中,指定了 GameConfig 的类型必须为 object(对象),且 items 属性类型必须为 array(数组)。

接下来在要校验的数据中指定 "$schema" 字段为该校验文件地址,比如下列 JSON 配置,故意把 items 字段的值设置为 string(字符串)而非数组:

{
"$schema": "https://www.code-nav.cn/latest.json",
{
"name": "yupi",
"difficulty": 5,
"items": "haha"
}
}

这样就能检查数据是否合法啦!很多主流的编辑器(比如 JetBrains 全家桶)可以自动识别校验文件,并且检查你的 JSON 输入是否合法。也可以使用 JSON Schema validation online 等在线校验 JSON Schema 的网页来查看效果:

3 分钟了解 JSON Schema

JSON Schema 功能非常强大,除了对字段类型的校验外,还支持判断字段是否必填、是否为某个值(支持正则表达式)、最大值最小值、字段个数、枚举等,甚至支持组合多个判断条件!

比如还可以给我们的游戏配置的难度字段添加校验,必须是 1 到 5 之间的数字,语法如下:

"difficulty": {
"type": "number",
"minimum": 1,
"maximum": 5
}

优点

了解什么是 JSON Schema 后,总结下它的优点:

  1. 对数据格式进行描述,提高可读性,帮助人类理解
  2. 让机器更理解数据,从而提供数据校验和提示输入等功能
  3. 提供了统一的数据规范语法,便于实现接口格式校验、自动化测试,甚至还能利用它自动生成代码!比如 jsonschema2pojo 工具,根据 JSON 生成 Java 类。

3 分钟了解 JSON Schema

总之,利用好 JSON Schema,能大大减少开发者们沟通的成本、保证代码的质量就对了。毕竟 JSON 可是当今前后端开发中最流行的数据交换格式啊!


看着他一脸懵逼的样子,我不禁笑到:这个鱼皮就是逊啦!

求求给这么逊的鱼皮 点赞 支持一下吧 ️

最后再送大家一些 编程学习资料

指路:https://t.1yb.co/qOJG

欢迎阅读 我的编程学习和大厂求职经历,不再迷茫!

指路:https://t.1yb.co/w66s

上一篇:STMPClient 发送邮件显示 不允许使用邮件名称.


下一篇:林轩田机器学习基石笔记1—The Learning Problem