JSON 是 Web API、配置文件、消息传输和跨语言数据交换中最常见的文本格式之一。它的规则很少,但 JSON 与 JavaScript 对象、Java Map 或某个 JSON 库的宽松输入模式并不完全相同。
1. JSON 是什么
JSON 全称是 JavaScript Object Notation,中文通常译为“JavaScript 对象表示法”。它是一种轻量、基于文本、与编程语言无关的数据交换语法。
JSON 借用了 JavaScript 对象字面量中的大括号、方括号、冒号和逗号,但它不是可执行的 JavaScript,也不规定程序内部必须使用什么对象或数字类型。对象可以映射为 Java 的对象或 Map、Python 的 dict;数组可以映射为 Java 的 List 或其他语言的列表。
2. 谁创造了 JSON,它怎样成为通用规范
类似 JavaScript 对象字面量的数据表达方式并不是由一个人从零发明的。Douglas Crockford 通常被认为是 JSON 的命名者和主要推广者。他回忆自己在 2001 年 4 月于 State Software 工作时认识到这种格式适合网络数据交换,随后建立 JSON.org 对语法进行整理和传播。
JSON 能快速普及,主要有几个原因:
- 浏览器可以很方便地处理这种结构,比当时常见的 XML 更精简。
- 对象和数组是几乎所有编程语言都具备的通用数据结构。
- JSON.org 提供了简单说明,并收录不同语言的解析库。
- Ajax 和 Web API 的兴起让轻量数据交换格式得到大量实际应用。
- 标准组织逐步固定了语法和互操作规则。
JSON 的标准化大致经历了以下阶段:
- 2001 年:JSON.org 首次向公众介绍 JSON。
- 2006 年:IETF 发布 RFC 4627,并注册
application/json媒体类型。 - 2009 年:ECMAScript 5 正式纳入 JSON 语法与
JSON.parse、JSON.stringify。 - 2013 年:Ecma International 发布 ECMA-404。
- 2017 年:IETF 发布现行互联网标准 RFC 8259;ECMA-404 第二版与其保持一致。
3. JSON 的语法结构
JSON 文本表示一个 JSON 值。最常见的是对象或数组,但现行标准也允许顶层直接是字符串、数字、布尔值或 null。
对象使用 {},属性名必须是双引号字符串,属性名和值之间使用冒号,成员之间使用逗号:
{
"name": "Wangz Tools",
"enabled": true,
"items": [1, 2, 3],
"settings": {
"theme": "system"
}
}
数组使用 [],元素有顺序,并且不同元素可以使用不同 JSON 类型:
["text", 42, true, null, {"id": 1}, [1, 2]]
对象成员和数组元素后面都不能添加尾逗号。对象属性名不能省略双引号,也不能使用单引号。
4. JSON 有哪些基础类型
JSON 只有六类值:
| 类型 | 示例 | 说明 |
|---|---|---|
| object | {"name":"A"} |
字符串属性名与值组成的集合 |
| array | [1,2,3] |
有序值列表 |
| string | "hello" |
双引号包围的 Unicode 文本 |
| number | -12.5e2 |
十进制数字 |
| boolean | true、false |
只有两个布尔字面量 |
| null | null |
明确表示空值 |
JSON 没有日期、二进制、枚举、undefined 或类实例类型。日期通常约定为 ISO 8601 字符串或 Unix 时间戳;二进制数据通常使用 Base64 字符串,具体语义必须由接口协议约定。
true、false 和 null 必须全部小写。True、FALSE、NULL 都不是合法 JSON。加上引号后,例如 "true",它就只是字符串,不再是布尔值。
5. 字符串与特殊字符转义
JSON 字符串必须使用双引号。以下字符使用反斜线转义:
| 转义 | 含义 |
|---|---|
\" |
双引号 |
\\ |
反斜线 |
\/ |
斜线,可选转义 |
\b |
退格 |
\f |
换页 |
\n |
换行 |
\r |
回车 |
\t |
制表符 |
\uXXXX |
4 位十六进制 Unicode 转义 |
双引号、反斜线以及 U+0000 至 U+001F 的控制字符必须转义。普通中文、英文和大多数 Unicode 字符可以直接写入 UTF-8 JSON,不要求全部转成 \uXXXX。
{
"quote": "他说:\"Hello\"",
"path": "C:\\Users\\Admin",
"lines": "第一行\n第二行",
"symbol": "\u00A9"
}
不要手工拼接用户文本来生成 JSON。应使用 Gson、Jackson、JSONObject 或其他序列化 API,让库负责正确转义。
6. Number 需要注意什么
JSON 数字使用十进制,可包含负号、小数和指数:
[0, -12, 3.14, 6.02e23, 1E-8]
以下写法不合法:
+1:数字开头不允许加号。01:整数部分不允许无意义的前导零。.5或1.:小数点前后都必须有数字。0xFF、0b10、077:不支持十六进制、二进制或八进制。NaN、Infinity、-Infinity:不属于 JSON number。
JSON 只规定数字的文本语法,不规定接收方内部使用 int、long、double 还是十进制定点数。很多环境会按 IEEE 754 双精度浮点数处理,因此只有 -9007199254740991 至 9007199254740991 范围内的整数可以稳定地在常见实现间精确互操作。
订单号、雪花 ID、银行卡号等“看起来像数字但不能丢失任何一位”的值应使用字符串:
{
"orderId": "9223372036854775807",
"amount": "19.99"
}
金额是否使用字符串、整数分还是十进制数,应由 API 契约统一规定。
7. 怎样在 JSON 里合法地写注释
标准 JSON 没有注释语法。下面两种写法都不是合法 JSON:
// 单行注释
/* 多行注释 */
JSONC、JSON5 以及某些编辑器虽然接受注释,但它们是 JSON 的扩展格式,不能假设普通 JSON 解析器也支持。
如果业务协议允许,可以把说明作为普通数据字段:
{
"_comment": "timeout 的单位是秒",
"timeout": 30
}
多条说明可以使用 _comments 数组。更通用的做法是把注释放在接口文档、JSON Schema 或相邻的 README 中。发送给外部系统前,应确认对方是否允许这些额外字段。
8. Java 常用 JSON 库
Java 常见选择包括:
- Jackson:Spring Boot 常用默认方案,数据绑定、流式解析和树模型都较完整。
- Gson:Google 提供,API 简单,适合普通对象序列化和反序列化。
- JSON-B:Jakarta JSON Binding 标准 API。
org.json/JSONObject:轻量树模型;Android 平台内置了相关类。
项目应统一选定一个主要库,不要在业务层同时混用多套对象模型。
9. Gson 常见用法
对象与 JSON 字符串互转:
import com.google.gson.Gson;
record User(String name, boolean active) {}
Gson gson = new Gson();
String json = gson.toJson(new User("Wangz", true));
User user = gson.fromJson(json, User.class);
反序列化泛型集合时需要保留泛型类型:
import com.google.gson.reflect.TypeToken;
import java.lang.reflect.Type;
import java.util.List;
Type type = new TypeToken<List<User>>() {}.getType();
List<User> users = gson.fromJson(jsonArray, type);
不需要定义 Java 类时,可以使用树模型:
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
JsonObject root = JsonParser.parseString(json).getAsJsonObject();
String name = root.get("name").getAsString();
boolean active = root.get("active").getAsBoolean();
不要把不可信文本直接拼进 JSON;调用 toJson 让 Gson 处理引号、反斜线和控制字符。
10. JSONObject 常见用法
Android 中可以使用 org.json.JSONObject 和 JSONArray:
import org.json.JSONArray;
import org.json.JSONObject;
JSONObject root = new JSONObject(json);
String name = root.getString("name");
boolean active = root.optBoolean("active", false);
String nickname = root.optString("nickname", "");
JSONArray items = root.optJSONArray("items");
getXxx 在字段缺失或类型不匹配时抛出异常;optXxx 允许提供默认值,更适合可选字段,但不能用默认值掩盖本应报错的必填字段。
构建 JSON:
JSONObject output = new JSONObject()
.put("name", "Wangz")
.put("active", true)
.put("items", new JSONArray().put(1).put(2))
.put("nickname", JSONObject.NULL);
String json = output.toString();
在 Android 的 JSONObject 中,需要明确输出 JSON null 时使用 JSONObject.NULL。直接向 put 传 Java null 可能删除该属性,因此两者不能混用。
11. 格式化、压缩和校验分别做什么
- 格式化只添加缩进和换行,不改变数据含义。
- 压缩只删除不必要的空白。
- 校验会按 JSON 语法解析文本并报告错误。
格式化工具无法判断字段业务含义是否正确。例如合法 JSON 中仍可能缺少必填字段、金额单位错误或对象结构不符合接口约定。这类规则应使用 JSON Schema、Java Bean Validation 或业务代码校验。