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 能快速普及,主要有几个原因:

  1. 浏览器可以很方便地处理这种结构,比当时常见的 XML 更精简。
  2. 对象和数组是几乎所有编程语言都具备的通用数据结构。
  3. JSON.org 提供了简单说明,并收录不同语言的解析库。
  4. Ajax 和 Web API 的兴起让轻量数据交换格式得到大量实际应用。
  5. 标准组织逐步固定了语法和互操作规则。

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 或业务代码校验。

参考规范