内容总览

JSON 说明与使用 思维导图

一、起源:跨系统数据交换的格式需求

JSON(JavaScript Object Notation,JavaScript 对象表示法)是一种轻量级、文本型的数据交换格式,独立于编程语言,便于人阅读和编写,也便于机器解析与生成。核心定位是承载前后端接口数据传输、配置文件与数据存储,本身不是编程语言,只是数据格式。

1.1 诞生背景

  • 在 JSON 出现之前,系统间结构化数据交换主要依靠 XML;XML 功能完备,但标签冗余、体积大,解析逻辑复杂,编写和阅读成本高,早期 Web 环境下浏览器端解析还会带来额外性能开销
  • Web 发展催生了浏览器前端与服务端互传结构化数据的需求,而 JavaScript 原生支持对象字面量语法,从中剥离出纯粹的数据表达形式,去除函数、undefined 这类无法跨语言传输的语法,即形成 JSON
  • JSON 由 Douglas Crockford 于 2001 年提出,2017 年正式以 RFC 8259 作为国际标准

1.2 存在意义

  • 要解决的本质问题是不同系统、不同编程语言之间的数据互通
  • 软件业务的本质是信息流转,不同模块、不同服务、不同设备产生的数据结构各不相同,缺少统一标准就无法传递信息
  • 作为中立的中间载体,把程序内部复杂的内存对象转换成一段可以网络传输、持久保存的文本,接收方再把文本还原回自身语言的数据结构
  • 不绑定任何一种编程语言,兼顾机器解析效率和人的可读性,以最低成本完成信息跨边界流转,支撑 Web 接口、分布式服务之间的数据通信

二、原理

2.1 特点

  • 文本格式,本质就是一段字符串
  • 跨语言:Java / Python / JS / Go / C# 等全部支持解析
  • 相比 XML 更简短,传输体积更小
  • 纯数据,不支持注释(标准JSON不允许注释,很多编辑器扩展jsonc/json5才支持注释)

2.2 限制

  • 不能写注释(标准JSON)
  • 没有变量、函数、循环、条件判断等程序逻辑
  • 只能表示六种基础数据类型:对象、数组、字符串、数字、布尔、null
  • 不存在内置日期类型,日期时间必须序列化为字符串或者数字时间戳

2.3 基础数据类型

类型 说明 示例
对象 object 键值对集合,{}包裹,key必须是双引号字符串,无序 {"name":"张三"}
数组 array 有序元素列表,[]包裹,元素可以是任意合法JSON类型 [10,20,30]
字符串 string 字符序列,必须双引号包裹,单引号不属于标准JSON "hello json"
数字 number 包含整数、浮点数,支持负数、科学计数法,不加引号 100、3.14、-20、1.2e5
布尔 boolean 只有小写 true / false,不加引号 true
空值 null 小写 null,代表不存在的值,不加引号 null

不支持:undefined、函数、正则、日期对象、二进制数据。这类内容序列化时会丢失或者转为null。日期一般序列化为ISO字符串或者时间戳。

2.4 语法规则

  1. 键(key)本质是字符串,必须使用双引号"包裹;单引号'、不带引号的标识符都是非法JSON。
  2. 键值之间用冒号 :,冒号前后空格不影响解析;键值对之间逗号 , 分隔。对象最后一个键值对、数组最后一个元素后面不能加尾随逗号,尾随逗号属于标准非法语法,部分解析器会直接抛出解析异常。
  3. 字符串必须使用双引号包裹,字符串内部特殊字符必须转义。
  4. 大括号{}代表对象,中括号[]代表数组。
  5. 大小写敏感:"Name" 和 "name" 是两个完全不同的key。
  6. key内允许包含空格、中文、横杠、点号等字符,前提是key被双引号完整包裹。
    • 合法示例:"key 1"、"用户名称"、"user.name"、"user-id"
    • 非法示例:key 1,没有双引号时,空格会被解析器识别为分隔符,直接报语法错误。
    • 工程约束:虽然语法允许key带空格、中文,但不推荐。在JavaScript中,带空格/特殊字符的key不能使用点语法访问,只能用方括号下标取值;Java、Go等静态语言需要特殊处理字段映射,容易出现序列化映射失败、数据库字段兼容问题。推荐命名:小写字母、数字、下划线组合,例如key_1。

合法示例

{
  "username": "admin",
  "age": 28,
  "isEnable": true,
  "score": null,
  "hobbies": ["读书", "骑行"],
  "address": {
    "province": "河南",
    "city": "鹤壁"
  }
}

常见错误写法

{
  name: "张三",   // key没有双引号,错误
  'age': 20,     // 单引号包裹key,不属于标准JSON,错误
  "list": [1,2,3,] // 数组末尾存在尾随逗号,标准JSON非法,错误
}

2.5 嵌套结构

  • JSON支持多层嵌套:对象里面可以包含数组,数组里面可以包含对象
  • 嵌套深度没有规范硬性限制,实际使用受解析器内存限制
{
  "id": 1,
  "title": "用户列表",
  "userList": [
    {
      "uid": 1001,
      "name": "小明"
    },
    {
      "uid": 1002,
      "name": "小红"
    }
  ]
}

2.6 转义字符

字符串内部的特殊控制字符,必须使用反斜杠 \ 进行转义,未转义会造成JSON语法断裂。

转义符 含义
\" 双引号
\\ 反斜杠
\n 换行
\t Tab制表符
\r 回车
\b 退格
\f 换页
\uXXXX Unicode字符,XXXX为4位十六进制编码

示例:

{
  "content": "这是一行文字\n第二行,里面有引号:\"测试\",反斜杠:\\"
}

三、实现

3.1 使用场景

  1. Web接口(RESTful API):后端返回JSON给前端,是当前Web服务数据交换的主流格式
  2. 配置文件:部分轻量项目使用,注意标准json无注释,需要注释的配置推荐jsonc/json5
  3. 本地存储:浏览器 localStorage、小程序本地缓存存储结构化数据
  4. 日志、数据导出、微服务之间数据通信
  5. NoSQL数据库:MongoDB使用BSON,结构和JSON高度相似,用于文档存储

3.2 JavaScript

// js对象 → JSON字符串(序列化)
const obj = {name:"张三",age:20};
const jsonStr = JSON.stringify(obj);

// JSON字符串 → JS对象(反序列化/解析)
const parseObj = JSON.parse(jsonStr);

// 普通key,点访问
console.log(parseObj.name);
// 带空格特殊key,必须方括号取值
const data = {"key 1": "test"};
console.log(data["key 1"]);

3.3 Java(SpringBoot常用,Jackson)

// 使用Jackson
ObjectMapper mapper = new ObjectMapper();
// 对象转json字符串
String json = mapper.writeValueAsString(user);
// json字符串转对象
User user = mapper.readValue(json, User.class);

补充说明:Java实体类字段名不支持空格,如需映射带空格的JSON key,使用注解@JsonProperty("key 1")指定映射名称。

3.4 Python

import json
# python字典转json字符串
data = {"name":"张三","age":20}
json_str = json.dumps(data, ensure_ascii=False, indent=2)

# json字符串转字典
res = json.loads(json_str)

# 读取带空格key
data = {"key 1": "value"}
print(data["key 1"])

3.5 校验与格式化工具

  • 在线校验格式化:JSON.cn、jsonlint.com
  • IDE插件:IDEA / VSCode 自带JSON格式化、语法校验

校验作用:快速定位逗号缺失、引号缺失、非法字符、尾随逗号等语法问题。上线前接口样例建议经过语法校验。

3.6 常见坑

  1. 不能注释:标准JSON不支持//单行注释、/* */多行注释,携带注释的文本会解析报错;VSCode里.jsonc后缀文件才支持注释。
  2. 末尾逗号:数组/对象最后一项后面不能加逗号,部分旧版本解析器直接抛出异常。
  3. key必须双引号,单引号不是标准JSON,部分语言解析器可以兼容单引号,但不属于RFC规范,跨系统对接会产生解析失败。
  4. 中文处理:中文可以直接写在JSON字符串内;部分老序列化工具会自动转为\uXXXX unicode编码,两种形式解析结果一致,不影响业务。
  5. 区分 null 和空字符串"":null代表字段不存在、无值;""代表字段存在,值为空字符串,二者业务含义完全不同,接口对接极易出现逻辑bug。
  6. 数字边界:JSON数字没有区分整型和浮点型,超大整数在JavaScript中会丢失精度;涉及长ID场景,建议序列化为字符串传输。
  7. 字符串转义遗漏:字符串内部包含双引号、换行符,不做转义直接写入JSON会直接破坏语法结构。

3.7 JSON 与 BSON / XML / YAML 对比

  • JSON:文本格式,Web接口首选,无注释,仅支持6种基础类型
  • BSON:二进制JSON,MongoDB使用,支持更多类型(二进制、日期、ObjectId),存储解析性能更好,不可直接人工阅读
  • XML:标签式标记语言,结构笨重,冗余标签多,现在HTTP接口基本淘汰
  • YAML:可读性更好,原生支持注释,多用于配置文件(k8s、docker-compose),语法缩进敏感,手写容易出错

四、总结

  • JSON是独立于编程语言的文本型数据交换格式,解决不同系统、不同编程语言之间的数据互通问题,定位是数据格式而非编程语言
  • 数据模型只有对象、数组、字符串、数字、布尔、null六种,没有注释、变量、函数、循环与条件判断,也没有内置日期类型
  • 语法硬性约束集中在三处:key必须双引号包裹、字符串内部特殊字符必须转义、对象与数组末尾不允许尾随逗号
  • key大小写敏感,语法允许包含空格与中文,但会影响点语法取值与静态语言字段映射,工程上通常使用小写字母、数字与下划线组合
  • 典型使用场景是Web接口数据交换、配置文件、本地存储、日志与数据导出、文档型数据库存储
  • 常见问题集中在注释、尾随逗号、单引号key、null与空字符串的语义差异、大整数精度丢失与转义遗漏
  • 与XML相比体积更小、解析更简单;与YAML相比不支持注释但缩进不敏感;BSON是其二进制扩展,面向文档存储

附录

附录A:JSON完整语法Demo示例

{
    "key":"key必须使用双引号括起来,单引号or不带引号都是不合语法的",
    "key2":"键值之间用冒号隔,键值对之间用逗号分隔,末尾不能有多余的逗号",
    "String":"字符串必须用双引号括起来",
    "caseSensitive":"Key是大小写敏感的,Key与key是不同的键",
    "dataType":{
        "description":"json支持的数据类型有:字符串、数值、布尔值、数组、对象、null",
        "string":"字符串必须使用双引号括起来",
        "number":"数值可以是整数或浮点数,不能使用引号括起来",
        "boolean":"布尔值只能是true或false,不能使用引号括起来",
        "null":"null表示空值,不能使用引号括起来"
    },
    "object":{
        "description":"这是一个对象",
        "key":"使用大括号括起来,键值对之间用逗号分隔,无序"
    },
    "array":[
        "这是一个数组",
        "可以使任意合法的json类型",
        "使用中括号括起来,数组元素之间用逗号分隔,有序"
    ],
    "number":"包含整数、浮点数,支持负数、科学计数法,不加引号",
    "integer":10,
    "float":10.0,
    "negative":-10,
    "scientific":1.23e+10,
    "boolean":"只有小写 true / false,不加引号",
    "boolean1":true,
    "boolean2":false,
    "null":"表示空值,不能使用引号括起来",
    "null1":null,
    "escape":{
        "description":"JSON字符串内部出现特殊字符时,必须使用反斜杠\\进行转义,否则会破坏JSON语法,导致解析失败",
        "escapeList":{
            "\\\"":"双引号,字符串内如果需要出现\",必须写成\\\"",
            "\\\\":"反斜杠,字符串内如果需要出现\\,必须写成\\\\",
            "\\n":"换行符,用于文本换行",
            "\\r":"回车符",
            "\\t":"Tab制表符",
            "\\b":"退格符",
            "\\f":"换页符",
            "\\uXXXX":"Unicode字符,XXXX代表4位十六进制编码,用于表示各类文字、特殊符号"
        },
        "escapeExample":"第一行文本\\n第二行文本,里面包含引号:\\\"引号内容\\\",反斜杠:\\\\"
    }
}

附录B:JSON 完整规范参考

标准文档:https://datatracker.ietf.org/doc/html/rfc8259