JSON的全称是JavaScript Object Notation，是一种轻量级数据交换格式。一个结构清晰的JSON示例不仅方便阅读，还能在接口联调时减少大量沟通成本。但JSON对格式要求非常严格，键名必须使用双引号、字符串必须包裹、不允许尾逗号和注释，这些规则使得示例的写法与普通JavaScript对象有很大区别。下面先从一个最基础的示例入手，把JSON的核心结构拆开看。

一、JSON示例的基础结构：对象、数组和值类型

JSON的结构主要由两种容器组成：对象和数组。对象使用花括号包裹，内部是若干组键值对，键必须是字符串，值可以是字符串、数字、布尔值、null、对象或数组。数组使用方括号包裹，元素之间用逗号分隔，元素类型可以不一致。下面这段示例基本覆盖了日常开发中常见的JSON数据类型。

{
  "name": "张三",
  "age": 28,
  "skills": ["JavaScript", "Python"],
  "address": {
    "city": "北京",
    "zip": "100000"
  },
  "active": true,
  "score": null
}

在这段示例中，name 和 age 属于基础键值对，skills 是数组，address 是嵌套对象，active 为布尔值，score 为null。注意数字不能加引号，加了引号就变成字符串，例如 "age": "28" 的语义与数字28完全不同。后端在反序列化时通常会做类型校验，类型不匹配可能导致接口报错。

数组中的元素虽然没有强制要求类型一致，但在实际项目中保持元素类型统一能减少解析端的判断逻辑。比如一个用户列表场景中，数组里每个元素都应该是结构相同的对象，而不是有的元素是字符串，有的是数字。这样前端遍历时不需要反复判断类型，代码会更加稳定。

二、JSON示例中的严格语法与高频错误

JSON的语法规则比JavaScript对象字面量严格，这是很多解析失败的根源。第一个硬性要求是键名必须使用双引号包裹，写成 name 或 'name' 都不合法。下面这段代码演示了几种常见错误写法。

{
  name: "张三",
  "age": 28,
  "skills": ["JavaScript", "Python",],
  "comment": "It's a demo"
}

错误一：键名缺少双引号；错误二：数组最后一个元素后保留了尾逗号；错误三：字符串使用了单引号。以上任何一种都会导致 JSON.parse 抛出异常。另一个常见错误是使用双引号字符串时没有正确转义内部引号，例如 "comment": "It's a demo" 其实是合法的，因为单引号不需要转义；但 "html": "<div class=\"box\">内容</div>" 不合法，因为内部双引号必须写成 \"。

还有一个容易被忽略的问题：JSON不支持注释。像 // 这是注释 或 /* 块注释 */ 放在JSON里会直接报错，这与JavaScript不同。如果确实需要注释，可以在键值对里增加类似 "_comment": "说明文字" 的字段，或者将JSON维护在支持注释的配置格式中，例如部分工具的JSONC格式。

三、JSON示例常见问题解答汇总

问题一：JSON和JavaScript对象字面量到底有什么区别？ 可以从几个方面区分：JSON只是一种数据格式，不能包含函数、undefined、日期对象等JavaScript特有类型；JavaScript对象字面量则是运行在JS引擎里的表达式。下面这段代码展示了对象字面量与JSON之间的差异。

// 这是JavaScript对象，不是合法JSON
var obj = {
  name: "张三",
  'age': 28,
  skills: ["JavaScript", "Python",],
  show: function() { console.log(this.name); }
};
// 转换为合法JSON后
var jsonStr = JSON.stringify(obj);
console.log(jsonStr);

可以看到，对象字面量里包含函数和单引号键，但经过 JSON.stringify 序列化后，函数会被直接忽略，单引号键会转换为双引号。这说明JSON的规则比JS对象字面量更窄，凡是超出JSON允许类型的字段都会在序列化时被丢弃或转换。

问题二：JSON中如何表示空值？ 空值统一使用 null，而不是 undefined 或 NaN。在字符串中如果需要表示空字符串，可以写 ""，它与 null 是完全不同的概念：前者是长度为0的字符串，后者表示没有值。后端接口文档如果没有特别说明，空字段建议使用 null。

问题三：JSON解析报错时怎么定位问题？ 大多数语言提供的JSON解析器会在错误信息中给出位置，但位置不一定直观。可以把JSON字符串复制到在线校验工具中查看，或者使用 JSON.parse 的异常捕获来输出错误。例如下面这段代码可以快速判断字符串是否合法。

var jsonStr = "{'name':'张三'}";
try {
  var data = JSON.parse(jsonStr);
  console.log(data);
} catch (e) {
  console.log("解析失败：" + e.message);
}

如果报错信息显示 Unexpected token ' in JSON at position 1，通常是遇到了单引号字符串；如果提示 Unexpected non-whitespace character after JSON，则可能是多了尾逗号或多余的字符。根据错误信息中的位置逐字符排查，很快就能发现非法写法。

四、实际场景中如何组织JSON示例

在实际接口联调或配置文件编写中，良好的JSON示例应该具备清晰的层级和统一命名风格。字段命名推荐使用驼峰或下划线，但同一份数据内不要混用。比如一个用户信息响应示例可以写成这样。

{
  "user_id": 1024,
  "user_name": "李四",
  "contact": {
    "email": "lisi@ipipp.com",
    "phone": "13800138000"
  },
  "roles": ["admin", "editor"]
}

好的示例还能帮助团队减少沟通成本。比如前后端约定返回结构时，提供一个规范的JSON示例，比用文字描述“返回一个对象，里面包含用户id和名称”要高效得多。需要特别注意的是，接口文档中的JSON示例必须能直接通过解析器校验，否则开发者复制过去调试会看到奇怪的报错，反而增加排查时间。

对于复杂数据，可以按业务模块拆分多个JSON示例片段，而不是把整份响应全部写在一个几百行的结构里。这样既能展示单个模块的字段，又方便后续维护。同时，示例中涉及敏感数据时要注意脱敏，不要把真实手机号、邮箱或密钥直接放进文档。