★ FEATURED ARTICLE 简介JSON作为轻量级数据交换格式在Web开发中承担着前后端通信、API数据交换等核心角色。这份基于Eclipse的JsonDemo示例工程面向Java初学者和需要快速掌握JSON解析与生成的开发者从键值对语法、基础数据类型到数组与嵌套对象均有完整演示。压缩包共22个文件包含2个Java源文件、编译后的class文件及Eclipse工程配置并预置14个jar依赖库覆盖多个json-lib版本与常用commons组件整体仅2.88MB目录结构清晰导入即可直接运行免去繁琐的环境配置。目前已有3577人浏览学习足见其作为入门示例的实用价值。示例不仅覆盖字符串、数字、布尔值、null、数组及嵌套对象等常用数据类型还对键名必须使用双引号、对象与数组结尾不能出现逗号等易错语法给出明确标注同时结合AJAX取数场景帮助读者直观理解JSON在前后端交互中的应用方式也可作为项目中的JSON处理模块参考。1. JSON完整例子为什么你需要一份能直接改的工程样本接手老接口时我通常会先找它的JSON样例文件——运气好的话能找到。这份JSON完整例子要解决的就是这种局面把订单业务场景里的结构设计、字段命名、日期格式、错误返回全部做成一份能直接对照的样本再配一套从解析到校验的代码链路。很多项目里JSON是最没存在感的部分没有设计文档也没有约束但它恰恰决定了前后端能不能正常对话。刚接触接口开发的人可以把这份例子当模板抄被历史数据结构坑过的人则可以拿它当体检清单。它不是语法手册是一份能跑、能改、能照着落地的工程参考。2. 数据模型设计从业务对象到JSON字段的映射2.1 字段命名先求全局统一再谈风格取舍JSON的字段名没有强制规范所以很容易出现“一个项目多种风格”的乱象。同一个系统里订单接口返回created_at用户接口返回createTime前端就不得不维护两套字段映射后端重构时还得写兼容层。真正负责的做法是在团队内部定死一个规则后端字段如果是snake_case出参JSON就继续用snake_case如果技术栈以Node.js为主就统一camelCase。关键从来不是哪个风格更优雅而是全项目必须一致。这份完整例子里固定使用snake_case因为它和Python、数据库字段天然同频接手的人看一个接口就能推断下一个接口的命名。字段内容本身也有讲究。习惯用名词表达“这条数据是什么”比如order_id、user_name而不是返回orderNo123这种混入业务编码规则的字段。布尔值推荐加is_前缀is_paid比paid的可读性高很多读代码时语义一目了然。数组字段用复数名items、detail_list都比item清晰单复数不一致会让你在排查时多绕一个弯。还有一个小细节统一使用单数还是复数表示集合我见过同一份数据里既有item又有items下游解析时踩了两次坑才意识到是命名不一致导致的。2.2 嵌套与数组三种结构关系怎么选拿到业务对象后第一反应往往是“有什么字段就全塞进去”结果就是嵌套四五层解析路径长得不忍直视。我一般按关系类型来取舍结构三种情况分别处理。嵌套对象适合一对一的伴随数据比如订单和下单用户订单详情页要展示用户昵称和等级那就直接嵌一个user对象数组适合同构的列表数据订单行项是一对多的典型场景用items数组数组里每个元素的结构必须保持一致ID引用适合跨接口复用的数据商品详情有独立接口时订单里只放sku_id前端需要详情再另发请求而不是把整个商品详情复制进每个订单行项。嵌套深度控制在三层以内这是我个人的一条线。订单对象里嵌useruser里再嵌address已经是第三层再往下塞经纬度对象前端取值就要写data.user.address.location.lat任何一层字段变化都会让整条链路失效。遇到需要更深的层级优先拆接口或把公共字段抽平而不是继续往下嵌套。下面这张表是三种结构的速查对照关系类型推荐结构典型例子一对一伴随数据嵌套对象订单中的用户一对多列表数组订单行项多对多 / 独立复用ID引用sku_id关联商品2.3 完整订单JSON示例与字段表组合一个覆盖主要场景的完整例子。这段JSON包含嵌套对象、数组、枚举、时间、可选字段后面章节的解析和校验代码都基于它展开。{ order_id: 20250601001, user: { user_id: 10001, user_name: zhangsan, phone: 13800000000, vip_level: 2 }, items: [ { sku_id: SKU001, name: 无线鼠标, quantity: 2, price: 99.90 }, { sku_id: SKU002, name: 键盘保护膜, quantity: 1, price: 29.50 } ], status: PAID, total_amount: 229.30, remark: , created_at: 2025-06-01T12:30:0008:00 }这份示例里藏着几个设计决策。status用字符串枚举而不是数字PAID一眼能看懂用1还要去查字典created_at用带时区的ISO 8601格式不同环境解析不会产生时间偏移remark是可选字段保留空字符串而不是直接缺省前端可以无脑展示。字段说明表在设计阶段就应定下来它不只是给人看的文档后面写Schema校验时required、type、enum全部以这张表为准。字段类型必填说明order_idstring是订单编号全局唯一userobject是下单用户信息user.user_idinteger是用户IDitemsarray是订单行项最少1条statusstring是PENDING / PAID / SHIPPED / FINISHEDtotal_amountnumber是订单总额remarkstring否备注允许空字符串created_atstring是ISO 8601格式带时区字段表的价值在于它把隐性的约定显性化了。没有这张表之前每个开发者对“必填”“可选”都有自己的理解有了它之后前后端、测试、新人都能以同一份标准对齐。JSON示例只是这张表的一种落地形态表本身才是真正的接口契约。3. 核心代码拆解解析、序列化与流式处理3.1 Python侧json.load与json.dumps的完整参数解析Python的json模块是处理JSON的主力先从文件读取说起。import json with open(order.json, r, encodingutf-8) as fp: data json.load(fp) print(data[order_id]) # 20250601001 print(data[user][user_name]) # zhangsanjson.load接收一个文件对象返回的数据类型有固定映射JSON对象对应Python的dict数组对应list字符串对应str数字是int或floattrue和false对应True和Falsenull对应None。这个映射是后面所有逻辑的基础调试时如果发现类型不对优先检查源头是不是混入了字符串数字。序列化方向用json.dumpimport json payload { order_id: 20250601002, items: [{sku_id: SKU003, quantity: 1}], } with open(order_out.json, w, encodingutf-8) as fp: json.dump( payload, fp, ensure_asciiFalse, indent2, sort_keysTrue, separators(,, : ), )参数各有用途ensure_asciiFalse让中文原样写出否则会变成\uXXXX转义序列indent2控制缩进便于人眼核对sort_keysTrue会让字典的键按字母排序对比两个JSON文件的差异时非常省事separators控制分隔符线上传输场景可以换成(,, :)来压缩体积。常见误用是把json.dumps当成唯一入口其实dump和dumps的区别只在第一个参数是文件对象还是返回字符串。真正容易翻车的是datetime这类Python原生对象json.dumps会直接抛TypeError。常规做法是写一个序列化兜底函数import json from datetime import datetime def default_encoder(obj): if isinstance(obj, datetime): return obj.isoformat() if hasattr(obj, __dict__): return obj.__dict__ raise TypeError(f无法序列化类型: {type(obj)}) data {created_at: datetime(2025, 6, 1, 12, 30)} print(json.dumps(data, defaultdefault_encoder))这段代码的执行顺序是先处理最常见的时间类型转成ISO 8601字符串如果是自定义类实例取__dict__属性输出两种情况都不满足就直接抛异常宁可在生成阶段暴露问题也不要让下游拿到无法识别的对象。default参数就是把“转不了该怎么办”的控制权交回开发者手上。解析字符串时建议捕获异常JSONDecodeError会携带行列号定位错误非常直接import json raw {order_id: 20250601001, status: PAID} try: data json.loads(raw) except json.JSONDecodeError as e: print(f解析失败: 第{e.lineno}行 第{e.colno}列, 错误: {e.msg})3.2 JavaScript侧从JSON.parse到类型防御前端拿到接口返回后的第一个动作通常是JSON.parse但直接parse有个隐患它假定返回的一定是合法JSON。网络请求经常出现状态码200但body为空字符串、或者返回了错误页面的HTML片段parse这些内容会直接抛异常。async function fetchOrder(orderId) { const res await fetch(/api/order/${orderId}); const text await res.text(); let data; try { data JSON.parse(text); } catch (e) { throw new Error(订单接口返回的不是合法JSON: ${e.message}); } const items Array.isArray(data.items) ? data.items : []; const total items.reduce( (sum, item) sum Number(item.price) * Number(item.quantity), 0 ); return { orderId: data.order_id, total: total.toFixed(2) }; }这段代码里有几个防御习惯。先res.text()拿到原始字符串再手动parse而不是直接用res.json()因为后者失败时错误信息更模糊Array.isArray检查防止数据结构异常时reduce直接崩溃Number()包一层是为了兜住历史数据里价格以字符串形式存在的情况很多团队早期把金额存成字符串规范改了但老数据还在。JSON.stringify的坑集中在undefined、null和特殊类型上const order { order_id: 20250601003, remark: undefined, plan_list: null, user_id: 10001n }; const str JSON.stringify(order); console.log(str);remark这个键会整个消失plan_list保留但值为nullBigInt类型的user_id会直接抛TypeError。undefined和null在业务眼里都是“没有”但JSON里面规则完全不同undefined被忽略null保留为字面量。如果接口契约里明确要求返回remark字段就要显式写null不能靠undefined占位。3.3 大JSON文件的流式读取json.load是一次性把整个文件载入内存对200MB的大文件来说解析出的dict结构占用的内存往往比文件本身还要大几倍。做历史数据迁移或批量同步时这个写法基本会把容器内存打爆。流式解析是更稳的方案import ijson # large_orders.json 结构: {orders: [ {...}, {...}, ... ]} with open(large_orders.json, r, encodingutf-8) as fp: parser ijson.items(fp, orders.item) for order in parser: process_order(order)路径参数orders.item是核心它让解析器只关注orders数组里的每个元素读到一个就通过生成器产出处理一个不会把整个数组堆进内存。处理完的元素随即被垃圾回收。ijson是高消耗场景的常用选择但日常小文件没必要上它优先保持json模块。还有一种按行读取的折中方案前提是文件本身就是JSON Lines格式即每行一个完整JSON对象。爬虫导出、日志采集这类场景天然符合NDJSON可以逐行loads内存占用恒定。但要注意普通带缩进的格式化JSON不能按行解析因为一条记录会跨多行按行切分得到的每一行都不是合法JSON。4. 校验与错误处理别让脏数据走进服务端4.1 Schema校验用jsonschema把字段表固化成代码上一章的字段表如果只活在文档里力量是不够的。jsonschema能把那张表直接变成可执行的校验规则from jsonschema import validate, ValidationError order_schema { type: object, required: [order_id, user, items, status], properties: { order_id: {type: string, minLength: 8}, user: { type: object, required: [user_id, user_name], properties: { user_id: {type: integer}, user_name: {type: string} } }, items: { type: array, minItems: 1, items: { type: object, required: [sku_id, quantity, price], properties: { sku_id: {type: string}, quantity: {type: integer, minimum: 1}, price: {type: number, minimum: 0} } } }, status: { type: string, enum: [PENDING, PAID, SHIPPED, FINISHED] }, total_amount: {type: number} } } try: validate(instance, order_schema) except ValidationError as exc: print(f校验失败: {exc.message}, 路径: {list(exc.absolute_path)})这段校验逻辑和字段表一一对应。required数组直接接管“必填列”type约束基本类型enum把状态枚举写死不在列表里的值直接拦截minItems保证订单至少有一条商品避免前端传出空订单。最实用的是absolute_path错误定位会精确到嵌套层前端把某个商品行项的价格传成字符串服务端能明确指出是items[0].price的问题。校验放哪一层很关键。我习惯放在路由层也就是业务逻辑入口之前先过结构校验再过业务校验最后才碰数据库。这样数据库层的异常不会被脏数据触发错误信息也归口统一不会出现接口返回200但数据库报主键冲突的尴尬场面。结构校验和业务校验要分开写前者管类型和必填后者管库存、权限这类需要查询才知道的规则混在一起会让Schema越来越膨胀。4.2 统一业务错误返回结构HTTP状态码能表达请求成不成功但表达不了业务失败的具体原因。订单创建失败可能是因为库存不足、价格被改、用户被风控三个原因都返回400前端没法区分。接口契约里应该定义一套统一的错误结构和正常响应体放在一起{ code: 40001, message: 库存不足, field: items[0].sku_id, request_id: req_8f61c2a9e0, timestamp: 2025-06-01T12:30:0008:00 }code是业务错误码与HTTP状态码解耦前端用code做文案映射message给用户直接展示field由校验层自动填充告诉调用方错在哪个字段request_id贯穿全链路排查问题时靠它串日志。错误码按模块分段是团队里验证过的做法订单模块用40000到40999用户模块用41000到41999看到code前两位就知道是哪个模块抛的错。4.3 日期、金额与非法字符的处理约定JSON只定义了六种类型没有日期、没有Decimal、没有字节流所以特殊类型怎么存必须提前约定。日期时间统一存ISO 8601字符串我一般用2025-06-01T12:30:0008:00这种带时区的格式按字典序排序就是时间排序主流语言都有现成解析器跨时区也不会产生偏移。不建议用Unix时间戳虽然传输体积小但秒和毫秒的约定在跨团队协作时经常打架。金额字段建议存字符串而不是数字。仔细看第二章节示例里的price是99.90这是给人看的但在JavaScript里解析JSON数字时99.90在浮点运算下会变成99.89999999999999前端合计金额时偏个几分钱是常事。账单、结算这类场景对精度敏感存字符串配合Decimal转换是目前比较稳的做法。普通计数场景可以用数字要建立明确的区分标准。null和缺省的含义也要分开。null表示“有这个字段但值为空”缺省表示“这个字段没出现”。前端展示逻辑里这两种情况的处理完全不同数据库写入时null会写NULL缺省则使用列的默认值。Schema的required数组能强制区分缺省的情况但null必须通过业务校验判断接口文档里也要写明每个字段何时允许null。5. 避坑与排查JSON项目里的高频翻车现场5.1 中文全部变成\uXXXX文件没法看现象dump出来的JSON文件里中文变成\u65e0\u7ebf\u9f20\u6807这种转义序列肉眼完全没法核对内容。很多开发者第一次看到会以为数据丢失了其实只是编码问题。原因json.dump默认的ensure_asciiTrue它会把所有非ASCII字符转成\u转义。文件本身是安全的但人没法读diff工具对比时也全是噪音。解决写文件时显式传ensure_asciiFalse同时open时指定encodingutf-8。with open(order_out.json, w, encodingutf-8) as fp: json.dump(data, fp, ensure_asciiFalse, indent2)补充一个容易漏的点Windows平台下open不传encoding会默认GBK和ensure_asciiFalse叠加会把UTF-8内容写坏。所以这两个参数要成对出现缺一不可。5.2 金额从99.90变成99.90000000000001现象接口返回的金额字段小数位变得很长前端每单算合计都会差几分钱财务对账怎么都对不上。原因IEEE 754双精度浮点数在表示有限小数时会有误差JSON的number类型在JavaScript里对应double99.90这种十进制小数没法精确表示。金额是特别容易被这个特性坑的字段类型。解决设计阶段把金额定为字符串入库用Decimal。存量数据如果已经是number类型写个一次性脚本转换import json with open(order.json, r, encodingutf-8) as fp: data json.load(fp) for item in data[items]: item[price] f{item[price]:.2f} with open(order_fixed.json, w, encodingutf-8) as fp: json.dump(data, fp, ensure_asciiFalse, indent2)这段脚本用f{item[price]:.2f}把浮点数格式化成两位小数字符串保持键名不变下游代码不用改字段路径。跑完之后再在Schema里把price的类型改成string防止新数据再以数字形态进来。5.3 循环引用序列化直接抛异常现象对ORM模型或图结构数据调用json.dumps时抛ValueError: Circular reference detected程序直接终止。原因对象之间存在互相引用的关系链比如父节点持有子节点、子节点又持有父节点的指针JSON序列化要求结构是树环形的引用没法表达。解决正常情况下应该从数据模型层面断掉循环序列化时只输出当前层级需要的字段def build_order_view(order): return { order_id: order.order_id, user_id: order.user_id, items: [ {sku_id: item.sku_id, quantity: item.quantity} for item in order.items ], }把关联对象拆成ID字段后端数据模型里的引用关系不直接体现在JSON里。比在序列化层做default处理器更干净。ORM模型做序列化时需要检查模型里backref这类反向关联字段是否被意外带进了输出这才是循环引用的主要来源。5.4 配置文件里的注释导致解析失败现象把项目里的ini或config文件内容硬改成JSON后缀或直接在JSON文件里写#注释json.loads直接报Unexpected character。原因JSON标准不支持注释也不支持尾逗号。把原来配置文件里的注释习惯带过来几乎是JSON新手必踩的坑。解决写JSON就遵守JSON自己的规则需要设计说明时把注释放到接口文档或字段表里而不是写进文件。如果配置文件确实需要注释最直接的办法是换YAML或TOML格式不要跟JSON标准较劲。尾逗号同理最后一个元素后多一个逗号Python的json模块会毫不留情地报错。编辑器保存时做一次JSON格式化可以提前拦住这类问题。5.5 深层嵌套JSON触发递归解析栈溢出现象JSON本身合法但Python在解析时抛RecursionError程序崩溃。原因数据嵌套层级太深超出Python默认的递归深度限制解析器递归处理导致栈溢出。这类问题常见于爬虫抓取的页面数据、用户提交的配置里包含多层嵌套的场景Schema校验拦不住它因为Schema不限制嵌套深度。解决在进入解析链路前先跑一遍深度检查def check_depth(obj, max_depth20, current0): if current max_depth: raise ValueError(嵌套层级超过限制) if isinstance(obj, dict): for v in obj.values(): check_depth(v, max_depth, current 1) elif isinstance(obj, list): for v in obj: check_depth(v, max_depth, current 1)这段代码递归遍历dict和list超过20层就抛异常。放在解析之前执行把潜在的栈溢出变成可控的业务错误。如果业务确实需要更深的层级可以在数据源头限制最大深度不要在解析时放任。生成JSON的一方也应该在自己的序列化层做同样的深度限制两侧同时约束才安全。6. 二次开发把完整例子改造成你自己的接口协议拿到这份JSON完整例子后第一件事不是改代码而是把第二章的字段表换成你自己的业务字段。字段表是契约的中心JSON示例、Schema校验、前端解析逻辑都围着它转。换字段时同步修改三处示例JSON里的字段名、jsonschema的properties和required、前端取值路径三处一处漏改都会在联调阶段暴露。字段表改完把静态示例改造成动态生成逻辑。订单响应不会永远是写死的JSON文件要封装成函数def build_order_response(order: dict, items: list[dict]) - dict: return { order_id: order[order_id], user: {user_id: order[user_id]}, items: [ {sku_id: i[sku_id], quantity: i[quantity], price: i[price]} for i in items ], status: order[status], created_at: order[created_at].isoformat(), }函数内部显式列字段不做全量dict透传这是防止接口多返回多余字段的关键。很多项目就是图省事直接返回整个ORM对象结果把内网地址、数据库主键全暴露到了前端。显式构造返回结构虽然多写几行但每个字段都为契约负责。改造后我一般做三步验证先起一个最小服务打一次真实接口看返回结构再跑一遍jsonschema全量样例确认新字段和required完全匹配最后用空items数组和非法status各测一次确认校验逻辑真的在拦截。这套验证走完心里基本有底。这份完整例子给我留下的习惯是每个接口上线前强制把字段、类型、必填列成表格再写Schema最后才写接口逻辑。从那以后几乎没有再见过“接口返回了前端才说缺字段”这种返工。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
