SheepDev

数据格式与结构化数据

JSON 报错了,应该改哪里?

使用工具

只改了一个设置,JSON 却无法读取。报错行只有一个普通的右括号。先别急着删除括号或数值,想想解析器读到这里时原本期待什么。

这里用虚构的小示例练习,不使用生产配置。目标不只是消除报错,而是在保留名称和值的含义的前提下,让接收方能够正确读取数据。

先看右括号前面

打开 JSON 格式化与验证,输入以下内容,保留末尾逗号后执行。先复现错误,再只改一个位置,确认失败原因。

修复前:末尾有逗号
{"name":"Ada","count":2,}

count 值后面的逗号表示后面还有成员,但紧接着却关闭了对象。因此右括号附近报错,并不一定是括号本身有问题,应检查它前面的分隔符。

修复后:只移除末尾逗号
{"name":"Ada","count":2}

再次执行后,检查 name 是否仍为 Ada,count 是否仍为数字 2。不要只看成功提示,还要确认修复过程中保留了应有的信息。

一次只改一处,反而更快

长配置出现多个错误时,很容易想批量替换引号和逗号。但一个未闭合的引号就可能改变后面整段的解析方式。应先从最前面的报错开始,检查附近少量字符。

  1. 自行保留原始数据的工作副本。
  2. 检查第一个错误及其前面的引号、分隔符和括号。
  3. 只做一处不改变含义的最小修改,再次执行。
  4. 成功后检查数值与条数,必要时对比修改前后。

看起来相似的引号也可能不同

逐个测试以下三个输入
{"name":"Ada"}
{'name':'Ada'}
{“name”:“Ada”}

第一个使用 JSON 的双引号,第二个是单引号,第三个是排版用弯引号。它们外观相近,却不是同一字符。经文档或消息复制后失效时,值得先检查这里。

不要把全文单引号盲目替换为双引号。O'Reilly 中的撇号属于内容,不是分隔符。必须区分字符串边界与字符串本身,否则会破坏正确数据。

修复语法时,是否把数字改成了字符串?

两者都能解析,但含义未必相同
{"count":2,"enabled":false}
{"count":"2","enabled":"false"}

加引号后能解析,不代表接收程序就接受:它可能要求数字或布尔值。字符串 false 不等于布尔值 false。格式化成功并不能证明符合应用的类型和业务要求。

相反,00123 这样的会员编号可能应该用字符串保留前导零。应判断它是用于运算的数量,还是用于识别的名称。改类型前先查接口约定,比猜测更可靠。

格式化让结构更容易看清

对象组成的数组
{"items":[{"name":"pen","quantity":2},{"name":"book","quantity":1}],"currency":"JPY"}

用两空格缩进格式化后,可以清楚看到 items 的两个元素。每个 name 与 quantity 属于同一商品,currency 在数组之外。缩进只是揭示原有关系,并未添加字段。

压缩会减少字符串之外多余的空白与换行。名称内部的空格仍是数据,不能一起删掉。检查时用格式化,需要紧凑表示时用压缩,两者都不等于修改实际值。

长编号要核对到最后一位

用于检查精度的公开示例
{"id":9007199254740993}

这个示例用于发现肉眼容易忽略的精度问题。SheepDev 的格式化使用保留精度的解析器,会保留末尾的 3。但转交给表格软件或其他程序后,仍需再次核对所有位数。

数字已被改动后再格式化,无法恢复丢失的原始位数,这也是保留原文的原因。改成字符串可能适合某些约定,但是否允许更改接收规范,需要另行判断。

值里面需要换行或引号时

字符串内的引号与换行
{"message":"He said \"hello\".\nNext line."}

句子里包含引号时,容易弄不清值在哪里结束。这里的反斜杠使后面的引号成为内容,而非字符串结束符。反斜杠加 n 表示换行。编辑器中可见的两个字符与读取后的换行,是不同的表示方式。

不要把转义换行与直接在带引号的 JSON 字符串内粘贴实际换行混为一谈。为消除错误而删掉换行,可能改变原文含义或显示效果。格式化只是整理表示方式,并不意味着可以改写内容。

粘贴的内容真的只有 JSON 吗?

复制整行日志时,可能连时间和 INFO 前缀一起复制。开发者控制台也可能显示对象的说明形式,而非响应正文。解析失败不代表 API 已损坏,应先确认复制的是 JSON 本身还是外层显示。

从聊天或文章复制示例时,还可能带上代码块标记或“输入示例”标题;也可能没有选到最后一个括号。先重新选择正文并检查首尾,再修改内容,可避免修复一个仅由复制造成的问题。

连续粘贴两个对象,会自动成为数组吗?

两个独立值,并非一个 JSON 文档
{"id":1}
{"id":2}

每行单独可以有效,但合在一起不一定是一份 JSON 文档。JSON Lines 等逐行存储形式采用不同的组织规则。SheepDev 的 JSON 格式化不会自动把独立文档合并成新结构。

接收方要求数组时的示例
[{"id":1},{"id":2}]

数组需要方括号和元素间的逗号。但应因为接收方要求数组才转换,而不是只为消除报错。逐行日志可能应保留原格式。修复语法与改变数据结构,是两项不同工作。

格式化成功后,还要检查什么?

能读取的 JSON 不一定是正确配置。quantity 为负数,或者字段误写成 quantitiy,语法上仍可能有效。必填字段与范围必须对照接收系统的规范检查。

交付修复时,可以说明“删除了末尾逗号,name 和 count 未变”,而不只是“可以格式化了”。明确原因与检查范围,能避免下一位同事重复排查。

参考资料

使用工具

指南 →