简介：这是一份面向初学者的 JSON 完整示例工程，帮助读者快速理解 JSON 轻量级数据交换格式的语法与实际应用。压缩包内共 22 个文件，以 14 个 jar 依赖包、2 个 Java 源码文件、2 个编译后的 class 文件为主，另附 json 笔记和工程配置文件，整体大小 2.88MB，目录结构清晰，可直接用于学习和二次调试。
工程通过 JsonDemo 演示对象、数组、嵌套结构以及 Java 中常见的 JSON 序列化与反序列化操作，json 笔记则梳理了键必须用双引号、最后一个键值对不能加逗号等易错规则，也覆盖字符串、数字、布尔值、null 和数组等数据类型的写法。对 Web 前端、后端以及移动端开发者来说，这份资源既能帮助理解请求与响应中的 JSON 数据格式，又能借助内置的 json-lib 等依赖快速跑通示例，减少环境配置时间。已有 3577 人学习/下载，代码完整、示例集中，适合课堂练习、自学入门和日常接口联调时参考。
1. 从一次接口联调事故说起：为什么你需要一份"JSON完整例子"
我有一次跟某前端同学联调，后端返回的 JSON 数组在浏览器里一 parse 直接报错。排查了半天，发现是某个字段的值里含了一个未转义的换行符，接口层没处理，前端拿到手就变成非法 JSON。后来我把这事记进了一个 JSON 示例项目里，把合法的、非法的、边界的情况全部整理成"完整例子"，联调前先拿例子验证一遍，再也没翻过车。这份资源的核心内容就是一套覆盖基础语法、嵌套结构、解析器差异、业务场景的 JSON 示例集，适合后端写接口、前端做 Mock、测试造数据，也适合刚学 JSON 的人照着抄。它不是一本教程，而是一堆可以直接拿走的真实样例和配套脚本。
2. 资源全景与目录结构：这份"JSON完整例子"里到底装了什么
2.1 技术栈与资源形态
JSON 本身不是编程语言，它依赖的是各语言内置解析器。所以这份资源的核心形态是"纯文本 JSON 文件 + 少量解析脚本"，脚本覆盖 Python、JavaScript、Java 三个方向，方便不同技术栈的人对照。资源不依赖任何重量级框架，只要你本机能跑 Python 3、Node.js 12+ 或 Java 8+，就能直接打开目录里的文件和代码。它跟常见 JSON 教程的最大区别是，每个文件不是只放一段语法演示，而是围绕场景给出完整字段、完整嵌套结构、甚至刻意放入容易出错的写法，用来验证解析器到底碰到什么会崩。
我拿到资源后第一反应是翻 README，里面写了一句话：所有 JSON 文件都是"双重用途"——既能当参考，也能当测试用例。比如basic/edge-cases.json里故意放了一些非法 JSON，你拿去给JSON.parse跑会直接挂，挂在哪个位置，就说明你写的解析逻辑缺了哪一层容错。这种设计思路，比单纯只给正确例子有用得多。
2.2 目录结构与文件清单
资源包解压后的目录结构大致是这样：
json-examples/ ├── README.md ├── basic/ │ ├── object.json │ ├── array.json │ ├── nested.json │ ├── unicode.json │ └── edge-cases.json ├── advanced/ │ ├── api-response.json │ ├── config.json │ ├── log-entry.json │ └──>{ "userId": 1024, "userName": "张三", "isVIP": true, "balance": 99.99, "tags": ["vue", "react", "小程序"], "profile": { "age": 28, "city": "某城市", "address": null }, "orders": [ {"id": 1, "amount": 299.00}, {"id": 2, "amount": 19.90} ] }这段代码几乎覆盖了 JSON 全部数据类型：字符串"张三"、数字1024和99.99、布尔true、空值null、数组tags、对象profile，以及对象数组orders。注意，JSON 的键必须是双引号包裹的字符串，数字没有整数和浮点之分，凡是数值统一按数字类型处理，299.00解析后会被当成299，小数位的精度取决于解析器。
这个例子真正的价值在于嵌套路径。如果你想取orders数组里第二笔订单的金额，路径是data["orders"][1]["amount"]，在写接口断言或者写模板时，路径一旦写错就是 undefined。很多新手在这里容易把数组索引从 1 开始，实际上 JSON 数组索引和大多数语言一样从 0 开始。另外，profile.address允许为 null，但很多接口在字段缺失时直接不返回这个键，解析出来的结果就变成了 undefined 而不是 null，这两种情况在业务代码里必须分开处理。
3.2 工业级场景样例：API响应、配置文件、日志结构化
advanced/api-response.json我每一次联调都会打开参考，它长这样：
{ "code": 0, "message": "success", "data": { "list": [ {"id": "p_001", "name": "手机", "price": 3999}, {"id": "p_002", "name": "耳机", "price": 499} ], "page": 1, "pageSize": 20, "total": 2 } }这个结构约定了一个通用接口返回规范：最外层用code表示业务状态码，0表示成功，非 0 表示失败；message放给前端看的提示文案；data里面放真正的数据。分页信息page、pageSize、total放在 data 内层，与列表平级，便于前端在渲染表格时直接取用。字段命名统一使用小驼峰，这在大多数后端语言里不需要额外映射，Java 和 JavaScript 都能直接对应属性名。
再看配置文件的例子advanced/config.json：
{ "appName": "order-service", "server": { "port": 8080, "timeout": 3000 }, "database": { "host": "192.168.1.10", "maxConnections": 20 }, "features": { "enableCache": true, "logLevel": "INFO" } }配置文件的特点是层级固定、字段名带语义，而且布尔值开关很常见。读这种 JSON 时，我一般会先定义对应的配置类或字典，再层层取字段，而不是直接访问深层路径，避免字段缺省时引发空指针。日志文件advanced/log-entry.json则展示了结构化日志的最佳实践：
{ "timestamp": "2025-01-01T08:00:00Z", "level": "INFO", "logger": "OrderService", "traceId": "a1b2c3", "message": "create order success", "context": { "userId": 12345, "orderId": "20250101001", "amount": 299.0 } }这里的时间格式使用 ISO 8601，带了时区后缀Z，比常见的yyyy-MM-dd HH:mm:ss更规范，日志采集器能直接识别。traceId用于串联一次请求的完整链路，在排查问题时尤其重要。context对象里放业务上下文，而不是直接平铺，能避免不同业务字段污染同一层级。工业场景的 JSON 实例，重点不是语法，而是约定。这份资源把约定固化成了文件，任何人照着写出来的接口返回都不会太离谱。
3.3 与主流解析器的对接示例：Python/JavaScript/Java
光有 JSON 文件还不够，配套的parsers目录给出了三种语言读取方式。先看 Python 的parse_python.py：
import json # 读取 advanced/api-response.json，必须指定 utf-8 编码，否则中文可能乱码 with open("advanced/api-response.json", "r", encoding="utf-8") as f: data = json.load(f) print(data["code"]) for item in data["data"]["list"]: print(item["name"], item["price"])json.load接收文件对象，json.loads接收字符串，二者别搞混。encoding="utf-8"是我每次都要强调的参数，Windows 下默认编码可能是 GBK，不指定 utf-8 会在打开含中文的 JSON 文件时直接抛UnicodeDecodeError。如果是生成 JSON，还需要指定ensure_ascii=False，否则中文会被转成\uXXXX序列。
再看 JavaScript 的parse_node.js：
const fs = require("fs"); const data = JSON.parse(fs.readFileSync("advanced/api-response.json", "utf-8")); console.log(data.code); data.data.list.forEach(item => console.log(item.name, item.price));JSON.parse是严格解析器，它对尾逗号、单引号、注释零容忍。如果你从浏览器控制台复制一个对象字面量，直接包成字符串传给JSON.parse，大概率会报错。所以我在浏览器里测试时，经常会用JSON.stringify先序列化一遍，再复制到代码里。
Java 端选择 Jackson 作为示例，parse_java.java核心逻辑是：
import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; ObjectMapper mapper = new ObjectMapper(); JsonNode root = mapper.readTree(new File("advanced/api-response.json")); System.out.println(root.get("code").asInt());Jackson 的readTree会把 JSON 读成JsonNode，它是树形结构，不要求你预先定义实体类，适合快速提取字段。但如果业务复杂，我更建议定义一个 Java POJO，然后用readValue反序列化成对象，编译期就能发现字段类型不匹配的问题。三种解析器各有特点，但核心链路一致：读取文本、解析成内存结构、通过路径访问字段。这一条链路在任何语言里都一样，区别只在 API 的写法上。
4. 避坑指南：JSON解析与生成中的常见翻车现场
4.1 尾逗号与单引号：JSON.parse直接报错
现象：从编辑器或浏览器控制台复制了一段对象字面量，想当作 JSON 传给JSON.parse，结果直接抛出SyntaxError。
原因：JavaScript 对象字面量允许单引号键名、允许尾逗号，甚至允许不加引号的键名，但 JSON 是严格子集，它只接受双引号包裹的键和字符串值，并且不允许尾逗号。很多人把对象字面量直接当成 JSON，却忘了 JSON 不是 JavaScript 对象。
解决：要么手工改成双引号并删掉尾逗号，要么用JSON.stringify先把对象转成标准 JSON 字符串。
// 错误写法：单引号键 + 尾逗号 const bad = '{name: "张三", age: 20,}'; console.log(JSON.parse(bad)); // SyntaxError // 正确写法：双引号 + 无尾逗号 const good = '{"name": "张三", "age": 20}'; console.log(JSON.parse(good)); // { name: '张三', age: 20 }那之后我处理外部传来的 JSON 字符串，都会先跑一个 JSON 格式校验脚本，再进入业务逻辑。这个例子里的edge-cases.json就是专门用来做这种测试的，你可以把它喂给解析器，看看它在哪个字符位置崩。
4.2 中文乱码：文件编码与ensure_ascii不一致
现象：用 Python 程序把字典写入 JSON 文件，本机打开是正常的，但在别的机器上打开就成了\u4f60\u597d这样的 ASCII 转义序列，或者直接乱码。
原因：json.dump默认ensure_ascii=True，会把所有非 ASCII 字符转成\uXXXX形式，虽然能保证文件在任意编码下可读，但人眼看不友好。还有可能是打开文件时没有指定编码，Windows 下默认用 GBK，写进去的中文再读出来就乱了。
解决：写入和读取都显式指定encoding="utf-8"，并在写入时设置ensure_ascii=False。
import json data = {"name": "张三"} # 错误写法 with open("out.json", "w") as f: json.dump(data, f) # 文件内容为 {"name": "\u5f20\u4e09"} # 正确写法 with open("out.json", "w", encoding="utf-8") as f: json.dump(data, f, ensure_ascii=False)ensure_ascii=False这个参数我每次写爬虫或者接口对接脚本时都带着，已经形成肌肉记忆了。如果你在生成接口返回时也遇到\u乱码，多半就是没关掉这个默认转义。
4.3 大整数与浮点精度丢失：数字类型不是你想的那样
现象：一个订单号9007199254740993，前端JSON.parse解析后变成了9007199254740992。另一个场景是金额0.1 + 0.2在多数语言里不等于0.3。
原因：JSON 的数字类型对应 JavaScript 的 Number，它采用 IEEE 754 双精度浮点，能精确表示的整数范围只有[-9007199254740991, 9007199254740991]，超过这个范围的数字都会被四舍五入。浮点小数本身在二进制里无法精确表示，所以会出现看似简单的加法误差。
解决：把大整数改用字符串表示，比如订单号字段写成"orderId": "20250101001"；金额用分为单位存整数，比如299.00元存成29900，或者在后端计算、前端展示时使用decimal类型处理。
const n = JSON.parse('{"id": 9007199254740993}'); console.log(n.id); // 9007199254740992 // 改为字符串后： const safe = JSON.parse('{"id": "9007199254740993"}'); console.log(safe.id); // 9007199254740993这是我在做交易系统时踩得最深的一个坑。从那以后，凡是可能超过2^53 - 1的标识，我在接口文档里都会注明"必须使用字符串"。
4.4 深度嵌套导致堆栈溢出：递归解析不是无限
现象：一个 JSON 文件嵌套了 1000 层，Python 的json.load执行到一半抛出RecursionError。
原因：大多数解析器在解析嵌套结构时都采用递归下降方式，递归深度受到语言调用栈限制，Python 默认递归深度约为 1000，如果层级太深就爆栈。虽然正常业务数据很少会嵌套几百层，但一个充满恶意结构的请求体可能触发这个问题。
解决：调用前用sys.setrecursionlimit临时调高递归上限，或者从源头上扁平化数据结构。最好的做法是业务层限制嵌套层级，比如配置文件最多允许五层，超过就判定为异常数据。
import json import sys # 造一个 1000 层嵌套的 JSON 字符串 s = "[" * 1000 + "0" + "]" * 1000 try: json.loads(s) except RecursionError: print("解析失败：嵌套过深") # 调高递归上限后再试 sys.setrecursionlimit(5000) data = json.loads(s) print("解析成功")调高递归上限只能解决一时的问题，如果这是外部请求的数据，我应该会在网关层做深度校验，超过阈值直接拒绝。深层嵌套本质上也是一种攻击面，不能指望解析器全扛下来。
5. 从零跑通：如何用这份例子快速构建你的测试数据与接口样例
5.1 两种使用方式：直接使用与二次加工
这份资源有两种常见的使用方式。第一种是直接拿来当接口 Mock 模板，打开advanced/api-response.json，把里面的list字段换成你自己的业务数据，然后导入到 YApi、Apifox 或者任意 Mock 服务里，前端就能立刻开始联调。第二种是用scripts/gen_mock.py做二次加工，根据你的字段定义生成一批随机假数据，用于压测、演示、单元测试。
我强烈建议你先把basic/object.json完整读一遍，确定自己熟悉所有 JSON 类型，再进入二次加工。因为当你需要生成随机数据时，本质上是先设计 JSON 结构模板，再写代码往模板里填值。结构都没想清楚，填值只会更乱。
5.2 用Python脚本批量校验JSON格式
整个资源包里的 JSON 文件都是手工维护的，改多了难免出错。scripts/validate_all.py就是用来做全量校验的：
import json import pathlib root = pathlib.Path("basic") for p in root.glob("*.json"): try: json.loads(p.read_text(encoding="utf-8")) print(f"{p.name}: OK") except Exception as e: print(f"{p.name}: FAIL {e}")这段代码用pathlib遍历basic目录下的所有.json文件，逐个用json.loads解析。解析成功输出文件名加 OK，失败就打印文件路径和异常信息。注意glob只匹配当前目录，不会递归子目录，如果你把文件放进了basic/sub/，这里就扫不到。想递归扫描可以用rglob("*.json")。运行方式很简单：
python scripts/validate_all.py我会把它接在 Git 提交前的一个钩子里，每次改完 JSON 都自动跑一遍，从源头避免把非法 JSON 提交到仓库。整套校验不需要装任何第三方库，Python 3 标准库就够。
5.3 把例子接入你的API Mock与单元测试
JSON 例子更实用的场景是接入单元测试。拿 pytest 举例，我可以把 JSON 文件当作参数化用例：
import pytest import json @pytest.mark.parametrize("case", [ "basic/object.json", "advanced/api-response.json", ]) def test_json_examples(case): with open(case, encoding="utf-8") as f: data = json.load(f) assert isinstance(data, dict)这里把两个 JSON 文件路径作为参数传给同一个测试函数，pytest 会自动生成两个用例。如果某个文件解析失败，测试会报出文件路径，方便定位。你也可以在断言里加上字段存在性检查，比如assert "code" in data，这样一旦接口返回结构发生变化，测试会立刻报警。当你的接口数量多起来后，我会给每个接口准备一个独立的 JSON 样例文件，测试函数只需要读取对应文件并断言关键字段，整套接口回归的成本会低很多。
5.4 参数说明与运行环境
运行环境方面，Python 脚本要求 Python 3.8 以上，pathlib和json都是标准库，不需要 pip 安装额外包。Node.js 脚本要求 Node 12 以上，只用到了内置的fs和JSON。Java 解析示例需要引入 Jackson 依赖，如果你用 Maven，需要在pom.xml里加上jackson-databind，版本使用 2.15 以上兼容 Java 8。
启动命令统一在资源根目录执行：
python scripts/validate_all.py node parsers/parse_node.jsJava 端编译运行：
javac -cp jackson-databind.jar parsers/parse_java.java java -cp .:jackson-databind.jar:jackson-core.jar:jackson-annotations.jar parse_java这里jackson-databind.jar的路径要换成你本机实际的 jar 包位置，如果你用 Maven 或 Gradle 工程，直接运行主类就行。整份资源没有配置文件、没有环境变量、没有端口依赖，所以从下载到跑通不会超过三分钟。
6. 二次开发指南：把"JSON完整例子"改造成你自己的数据工厂
6.1 用模板函数生成随机JSON
资源自带的gen_mock.py是一次性脚本，但我会把它改造成可复用的函数。比如根据业务需要生成用户数据：
import random import json def gen_user(uid): return { "userId": uid, "userName": f"user_{uid}", "isVIP": random.choice([True, False]), "balance": round(random.uniform(0, 1000), 2) }这个函数接收一个uid，返回一个完整 JSON 对象，每次调用的数值都有随机性，适合批量造测试数据。关键点是字段名和类型必须与basic/object.json保持一致，否则前端拿到手会报字段 undefined。
6.2 把生成器接到命令行
为了让组里不懂 Python 的同事也能用，我给它加了一个argparse命令行入口：
import argparse import json parser = argparse.ArgumentParser() parser.add_argument("--count", type=int, default=1) args = parser.parse_args() for i in range(args.count): print(json.dumps(gen_user(i + 1), ensure_ascii=False))执行python gen_mock.py --count 5就能在终端输出五个用户 JSON，用重定向写入文件就能变成 Mock 数据源。ensure_ascii=False依然是必选项，否则中文 userName 会变成\u序列。从那以后，我每次联调前都会先跑一遍生成脚本，用统一的样例数据取代手工改文件，字段漏改、类型写错的概率低了很多。希望这份资源和你自己的二次改造，也能帮你少加几天班。
本文还有配套的精品资源，点击获取
