JSON与JSON-RPC：数据格式与远程过程调用协议的区别及选型指南

“JSON”和“JSON-RPC”这两个词在技术讨论里经常同时出现，但很多人其实是带着疑惑在使用它们：你说JSON是一种数据格式——没错；那JSON-RPC呢？看起来也是一堆JSON，怎么又叫协议？一次跟团队里刚转后台的前端同学排查线上问题，对方把JSON-RPC接口返回的一个错误对象当普通JSON数据去解析，折腾了半天才弄清楚根本不是一回事。从那以后我就觉得，这种底层概念的混淆远比某个API用错更值得专门写一篇文章讲清楚。

这篇文章想解决的核心问题就一个：搞清楚JSON和JSON-RPC到底差在哪里，各自解决什么问题，什么场景该用谁，什么场景不该混着用。我不打算只念定义，而是会把语法细节、协议规范、实际项目里的坑都摊开聊，既适合刚入门的初级开发者建立正确认知，也适合写过不少接口但一直没系统梳理过协议逻辑的工程师查漏补缺。

1. 本质定位：一个是被传输的“话”，一个是双方约定的“对话规则”

1.1 JSON是什么：一种语言无关的数据表示语法

JSON，全称JavaScript Object Notation，本质是一套文本序列化规则。它规定了键值对怎么写、数组怎么写、字符串怎么转义、数字和布尔值长什么样，以及嵌套结构如何组合。它没有一个“方法”“请求”或“响应”的概念，更不关心数据从哪来、要到哪去、做什么用。你把它写入一个.json配置文件也行，从HTTP接口返回给前端也行，存进PostgreSQL的jsonb字段也行，它都能老实承载数据，但本身不承载任何业务语义。

打个比方：JSON就像运输商品时用的标准集装箱。集装箱本身定义了尺寸、材质、锁扣规则，但里面装的是衣服还是零件，集装箱完全不管。你可以在码头用它，也可以在火车上用它，甚至临时用来装垃圾也没人有意见——只要符合集装箱规范。

1.2 JSON-RPC是什么：一种基于JSON文本格式的远程调用协议

JSON-RPC则复杂得多。它是一个把“调用某个过程并取回结果”这件事，通过JSON文本来表达的远程过程调用协议。目前主流使用2.0版本，它明确规定了调用方和被调用方之间的消息结构：请求里必须有jsonrpc版本号、method方法名、params参数和id标识；响应里必须有jsonrpc、result或error，以及和请求对应的id。它还定义了错误码的范围和含义，比如-32700表示解析错误，-32601表示方法不存在。

继续用集装箱类比：JSON-RPC不是集装箱，而是码头装卸货物的整套作业规范。它规定了你必须先发一个“提货申请单”（request），申请单里要写清楚货单号（id）、要干什么（method）、随货资料（params）；对方必须给你回一个“作业回执”（response），回执里要么有结果（result），要么有异常说明（error）。没有这套规范，集装箱再多，装卸双方也没法配合干活。

1.3 核心区别一目了然

这里我习惯把区别浓缩成一张表，跟团队培训和接口文档放一起用：

这张表能直接回答“为什么不能把JSON-RPC当普通JSON来解析”——因为JSON-RPC的响应对象里的error字段本身就是一个结构化的错误对象，它需要按协议语义来解读；而普通JSON里的error字段可能只是一个普通的业务字段。语义层完全不同。

1.4 一个容易反复踩的“嵌套”误区

还有个细节：JSON-RPC本身是构建在JSON之上的。也就是说，JSON-RPC的每个请求或响应，本质上就是一个JSON对象。这导致很多人在实现JSON-RPC服务端时，第一步先用JSON解析库把消息解析出来，然后再按JSON-RPC规则去判断字段。这个流程没错，但要注意层次：JSON解析是第一步，协议语义判断是第二步。如果只做第一步不执行第二步，你只是“接收了JSON”，并没有“完成一次JSON-RPC调用”。

我后来排查线上问题，习惯先问一句：“这段JSON是要给人读的配置，还是要给程序执行的调用消息？”目的不同，后续的处理逻辑完全不一样。

2. 拆解JSON：从语法到语言库再到存储工具链

2.1 基础语法里的几个“反直觉”点

JSON语法看起来简单，越简单越容易出错。字符串必须用双引号，不能像JavaScript对象那样用单引号或不写引号；末尾不能有逗号，传统编程语言里写数组和对象喜欢留个trailing comma，在JSON里直接解析报错；数字没有NaN、Infinity这类概念；注释符号完全不支持——是的，JSON官方规范里就没有注释。网上经常有人问“json怎么加注释”，答案就是不能加，非要加可以用_comment字段或者改用JSON5、YAML等支持注释的格式。

另一个容易忽略的点是最外层的类型。很多人潜意识里认为JSON最外层一定是“键值对包裹的大括号”，其实JSON的最外层可以是数组、字符串、数字甚至布尔值。比如["a","b"]、"hello"、123都是合法的JSON文档。现代很多工具已经能正常处理，但某些老旧的解析器或配置框架仍然只接受对象作为顶层结构，所以兼容性设计时我一般约定顶层用对象。

2.2 常见语言中的JSON处理与那个著名的Date报错

JSON只支持字符串、数字、对象、数组、布尔和null，没有日期类型。这就导致几乎所有语言在把时间对象序列化时，都能搞出一堆个性化方案：有的是时间戳数字，有的是ISO8601字符串，有的是自定义格式"yyyy-MM-dd HH:mm:ss"。反序列化时最经典的就是报错：

code复制JSON parse error: Cannot deserialize value of type `java.util.Date` from String ...

这个错误几乎每个Java后端工程师都见过。根子是后端DTO里声明的是Date类型，但前端传过来的字符串格式不符合Jackson反序列化时的默认格式配置（通常期望时间戳或ISO格式）。解决方案无非两种：一是前端改成传时间戳；二是在后端给对应字段加@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")注解，或者全局配置ObjectMapper设置dateFormat。我建议小项目用字段注解，大项目直接全局配置，避免漏改字段。这个坑同样会出现在Python的json.loads上，因为标准库JSON模块本身不解析日期字符串，你需要dateutil.parser.parse手动处理。

Python处理JSON比较直接的套路是：

python复制import json
from datetime import datetime

raw = '{"name": "book", "publish_time": "2025-06-01T10:00:00Z"}'
data = json.loads(raw)
print(data["name"])
# 日期字段需要手动转换
dt = datetime.fromisoformat(data["publish_time"].replace("Z", "+00:00"))

如果不想手动处理，可以用orjson、pydantic这类库做自动字段绑定和类型校验。数据规模大时orjson的序列化速度比标准库快不少，我实测在百万级记录导出场景下性能差距非常明显。

C语言场景下，常用的库是cjson，使用cJSON_Parse得到一个cJSON *对象，再用cJSON_GetObjectItem取字段。但C语言没有自动内存管理，用完就得cJSON_Delete，不然内存泄漏够喝一壶。

2.3 JSON在数据存储、数据处理和配置场景里的角色

在数据库领域，PostgreSQL的JSON支持已经非常成熟，值得单独说说。json类型是原样保存文本，每次查询都要重新解析；jsonb类型则是二进制格式存储，查询时不需要反复解析，还支持索引和运算符，比如->、->>、@>、?等。实际项目里我基本默认选jsonb，除非你有极强的“保留插入时的顺序、空格”这类需求，否则完全没有理由用json。PG里常用的函数也有讲究，例如jsonb_array_elements把数组展开为行集，jsonb_each把键值对展开为两列，jsonb_path_query则提供了接近SQL标准的JSONPath查询能力。处理嵌套JSON做报表统计时，这几个函数可以省掉大量应用层代码。

Spark读取JSON也是日常高频操作。直接用spark.read.json("path")能自动推断schema，但推断机制在数据字段稀疏或类型不一致时容易翻车，比如同一列有时整数有时字符串，这是经验之谈。我一般建议手工定义schema或者用samplingRatio控制采样比例，宁可在读取阶段多花点时间，也别让后续SQL因为类型不匹配而跑挂。

Kettle（PDI）解析JSON则需要借助“JSON Input”步骤，指定路径表达式（如$.results[*].name）来逐字段抽取。要注意Kettle老版本对嵌套数组的处理需要额外使用“JSON Path”写法，调试时建议先在JSON Sample里验证路径，再去跑转换。

另一个有意思的场景是Blender和ComfyUI。Blender导出模型到JSON，实际上是把场景树、网格顶点、材质参数等按约定的schema序列化，方便程序化建模或Web端展示。ComfyUI导入工作流JSON，本质上是把节点图、连线、参数都写成JSON，再用GraphQL式的语义去恢复。这两个例子告诉我们：JSON作为配置文件时，其“schema结构”比“语法合法性”更关键——你必须完全遵守应用定义的字段结构，否则程序能解析却无法使用。也常有人问“JSON文件用什么打开”，正确答案是：任何纯文本编辑器都能打开，但如果你想格式化、校验、按路径查询，需要VS Code插件、在线工具或者本地命令行工具（如jq，后面会提）。

3. 拆解JSON-RPC：协议规范、调用模型和选型逻辑

3.1 协议里那几个必须记牢的字段

JSON-RPC 2.0的请求对象长这样：

json复制{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": [42, 23],
  "id": 1
}

关键点在于jsonrpc字段必须精确为字符串"2.0"，method为要调用的方法名，params是数组或对象，二选一；id必须是一个标识符（字符串或数字），不能是空对象、数组或null。id的意义是把响应和请求关联起来，因为有并发或批量场景，没有这个标识你根本不知道哪个响应对应哪个调用。

通知（notification）是JSON-RPC的一个特殊形态：请求中没有id字段。这种消息约定为“我不需要你返回结果”，服务端不应返回响应。适合心跳、日志上报这类不需要确认的场景。

批量调用（batch）允许你把多个请求放在一个JSON数组里一起发出去，服务端返回一个数组的响应。批量里的每一个元素都是独立请求，也就是说你可以混入普通调用和通知，服务端会对每个有效元素单独处理，但整个批次的解析错误需要在最外层返回一个错误响应。这里的细节很容易在自实现协议时出错，我建议直接用成熟的库，别自己手搓批量逻辑。

响应对象有两种形态，成功时：

json复制{
  "jsonrpc": "2.0",
  "result": 19,
  "id": 1
}

失败时：

json复制{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found"
  },
  "id": 1
}

注意result和error不能同时出现，id必须与请求一致。如果请求的id丢失或不可用，响应中的id设为null。协议还规定了一组保留错误码：-32700解析错误、-32600无效请求、-32601方法不存在、-32602参数无效、-32603内部错误，以及-32000到-32099间的服务器错误码。应用可以定义自己的业务错误码，但范围应该避开上面的保留区间。

3.2 一次真实调用流程的完整对话

我拿一个简单的计算器服务举例。客户端发起调用：

json复制{"jsonrpc":"2.0","method":"add","params":[10,5],"id":"req_001"}

服务端校验版本和方法后返回：

json复制{"jsonrpc":"2.0","result":15,"id":"req_001"}

如果客户端传了错误的方法名：

json复制{"jsonrpc":"2.0","method":"div","params":[10,2],"id":"req_002"}

服务端回：

json复制{"jsonrpc":"2.0","error":{"code":-32601,"message":"Method not found"},"id":"req_002"}

这里的处理逻辑很清晰：先解析JSON，再验证jsonrpc版本；判断method是否存在；校验params；执行方法；把结果包成result；异常则映射到合适的错误码。这个流程和普通HTTP API的后端路由很像，但JSON-RPC把所有调用信息都放进了请求体，而不是依赖URL路径或HTTP动词来区分操作。也因此，JSON-RPC可以很自然地跑在各种传输层上面：TCP、HTTP、WebSocket、消息队列都行。只要双方能收发字节流，协议本身保持完整即可。

3.3 JSON-RPC和REST、gRPC、XML-RPC的取舍

做技术选型时，JSON-RPC经常被拿来和REST对比。REST围绕资源（Resource）设计，通常用HTTP方法表达操作语义，URL表达资源路径，状态码表达结果状态。这种设计在面向外部系统的公开API中更常见，因为它语义清晰、容易缓存、方便检索。JSON-RPC则围绕动作（Action）设计，客户端直接告诉服务端“执行哪个方法”，语义直白，请求和响应的结构高度固定，开发客户端SDK时很容易做统一封装。

gRPC走的是HTTP/2 + Protobuf高性能路线，强类型、强约束、代码生成能力强，适合内部高并发微服务。但代价是需要维护.proto文件，工具链较重。JSON-RPC的实现成本低、跨语言调试难度低，任何一门语言都能随手解析JSON，非常适合内部工具、中小服务、脚本间调用和需要快速上手的场景。

XML-RPC是JSON-RPC的老前辈，结构也是请求响应分离，但XML格式冗长、解析开销大。JSON-RPC基本是继承了它的思想，把载体换成了更轻量的JSON。又因为JSON-RPC协议文档简单到十几分钟能读完，很多区块链项目、钱包协议、动态语言之间的IPC都选择它。这并不奇怪，像Ethereum的JSON-RPC API已经成了事实标准，官方文档里列出了大量eth_开头的方法。

3.4 跟WebSocket、消息队列结合时的特殊注意点

既然JSON-RPC与传输层无关，就容易想到通过WebSocket做双向调用：服务端也可以主动给客户端发请求，比如推送任务。这种双向通信模型在REST里很难优雅实现，在JSON-RPC里就自然得多——因为协议本身不区分谁是“客户端”谁是“服务端”，只看谁发起请求、谁返回响应。我在自研在线协作工具时，就用了WebSocket承载JSON-RPC，实现服务端向特定浏览器节点发起“采集数据”的方法调用，体验比轮询舒服得多。

不过这样用的时候要特别注意连接层和协议层的隔离：WebSocket负责维持连接、心跳、重连，JSON-RPC负责消息语义。千万不要把连接状态错误直接塞进JSON-RPC的错误码里，否则上层代码会混乱。一个约定俗成的做法是：网络层错误用连接事件通知，应用层错误才用JSON-RPC的error结构体返回。

4. 实际场景选型：什么时候用JSON，什么时候上JSON-RPC

4.1 配置、数据交换和API响应体直接用JSON

如果你只是要把一份数据从A传到B，例如导出用户列表、同步商品信息、存一份报表快照，那么直接用JSON数据格式就够了。不需要请求响应语义，不需要错误码，只要双方约定好字段结构和类型就可以。前端拿到JSON之后用JSON.parse解析，再用各种json查询函数（如Array.find、filter，或者新出的Object.fromEntries组合操作）去提取数据，完全不会有认知负担。

配置文件也是JSON的主场。我们常见的VS Code launch.json里serverArgs字段配置调试参数，一只Java服务、一个Node进程，它里面的type、request、program都是调试器定义好的字段，不是JSON-RPC。书源合集JSON、音乐源JSON、影视源接口JSON更是如此：它们本质上是“数据文件+接口地址列表”，播放器或阅读器解析后，按自己的逻辑去请求。这类文件经常被网友整理成2026最新音源json、2026有效接口源json等合集，主站应用只需要把它当成普通JSON下载、解析、合并，完全不需要RPC。

4.2 需要“调用方法”时，JSON-RPC是轻量答案

一旦双方之间不是“传数据”而是“执行操作”，并且你不想为此设计一整套REST资源模型，JSON-RPC就是最合适的轻量答案。典型例子包括：

• 内部微服务间少量方法调用，不想引入gRPC的重量级代码生成；
• 浏览器扩展与本地守护进程通信，通过stdin/stdout传递JSON-RPC消息；
• 多语言脚本之间的IPC调用，例如Python调用Node的服务方法；
• 区块链钱包、节点客户端提供的方法访问，如eth_getBalance、eth_sendTransaction，它们是标准的JSON-RPC方法；
• 大模型和外部工具之间的函数调用协议，很多地方也采用类似JSON-RPC的请求响应结构。

选择时有一个简单判断准则：如果你脑子里想的是“有没有某个函数/操作可以执行”，那就倾向于JSON-RPC；如果脑子里想的是“有哪些数据需要读取或保存”，那倾向REST或纯JSON。

4.3 大模型生成JSON与“指定格式输出”的实践启发

在AI工作流里，JSON和JSON-RPC的区别也会体现得很现实。很多人让大模型“生成指定格式的JSON”，例如把TXT文档转成用于微调的JSON数据集，或者让对话框输出一条符合接口要求的请求消息。这时候你关心的是语法是否合法、字段是否存在，属于纯JSON层面的问题。通常做法是给模型一个few-shot示例，并要求它只返回JSON代码块，再用一个JSON解析器严格校验。我在Python里经常搭配ollama和datasets库，把原始文本批量交给模型生成{"instruction":..., "input":..., "output":...}这类JSON行，然后过滤解析失败的样本。核心经验是：不要让模型输出多余的解释文字，宁可多给一个示例，也不要让它自由发挥。

反过来，如果你想通过大模型平台暴露一个可编程的工具调用接口，那么平台常常会定义类似JSON-RPC风格的方法调用，比如工具名是method，参数是params，调用结果里带上错误信息。理解这套“格式 vs 协议”的分层，对调试AI Agent的调用链非常有帮助：格式错误先看JSON语法，协议错误再看方法名、参数映射、错误码。

4.4 如何识别一份数据里到底有没有协议语义

我在实际项目评审里经常看到有人把“请求接口返回的JSON”和“JSON-RPC响应”搞混。怎么快速判断？看结构上有没有jsonrpc字段。如果某个顶层对象里明确写着"jsonrpc":"2.0"，那必须先按JSON-RPC语义处理。如果只是返回一个普通的业务对象，比如{"code":0,"data":{...}}，那就算错误结构里的error字段写得再像协议错误，它也只是业务数据。

有个更简单的经验：JSON-RPC的响应对象里result或error是协议固定字段，往往直接对应方法调用的结果；普通JSON API里常见的是status、code、message、data这类业务约定字段。前者关心“调用是否成功”，后者关心“业务处理状态”，语义不对等。

5. 常见问题与排查技巧实录

5.1 JSON解析阶段最容易翻车的几个点

第一个坑是BOM头。Windows下用记事本另存为UTF-8格式，偶尔会带上BOM。Python的json.loads遇到BOM会直接报Unexpected UTF-8 BOM，需要在读取文件时指定encoding='utf-8-sig'。Java用Jackson时则一般会自动处理，但老版本也会翻车。

第二个坑是注释和尾逗号。很多人在JSON里习惯性写//注释或{ "a": 1, }这种尾逗号，解析器直接报错，然后来问为什么。解决方案很简单：写JSON时脑子里就记住“JSON不是JavaScript”，不支持的语法一律不写。

第三个坑是转义。JSON字符串里的反斜杠需要转义，常见于文件路径、正则表达式、Windows路径。比如C:\Users\name必须写成"C:\\Users\\name"，服务器返回的日志里反斜杠处理失误经常导致解析失败。调试这种问题最快的方法是打印原始报文，而不是打印解析后的对象。

第四个坑是数字精度。JSON标准没有规定数字精度，但JavaScript和不少动态语言在解析大整数（超过2^53）时会出现精度丢失。如果你的接口返回雪花ID或超过16位的整数，建议后端把它们序列化成字符串，否则前端解析后数值会对不上。这个问题在Java后端尤其常见。

如果遇到“JSON Parse Error: Cannot deserialize value of type java.util.Date from String”这种，根源就是日期格式不匹配，解法在2.2节已经写过，这里再补充一个排查方法：先把Underscore（_）两端字段打印出来，看服务端到底收到的是一个什么格式的字符串；再用一个简单的测试类用同样的ObjectMapper执行readValue，定位到具体字段。

5.2 JSON-RPC调用阶段的协议错误速查

JSON-RPC错误码虽然不多，但调试时非常实用：

之前遇到过一个典型的422状态码错误，日志写着unexpected status 422 unprocessable entity: failed to deserialize the json body。这其实不是JSON-RPC标准里出现的，而是HTTP层把业务校验失败映射到422，JSON解析阶段失败也可能触发。排查时要区分到底是“HTTP状态码反映业务失败”还是“HTTP响应体本身不可解析”。前者要去看服务端业务逻辑，后者要去看请求JSON到底哪里不合法。

还有一个来自自动化的常见问题，用Ansible调用API时出现module result deserialization failed: no start of json char found ansible，这是核心模块在尝试解析非JSON响应造成的。一般是服务端返回了错误页、空字符串、或带了文本干扰内容。排查思路是打印未处理前的原始响应，确认是否有BOM、空格或多余文字。最好在代码里对响应做一次strip()后再尝试json.loads。

5.3 工具链里的实用排查技巧

很多人已经习惯用jq。它是Linux下一个非常好用的JSON命令行处理工具，可以格式化、过滤、修改、遍历JSON。常用几个命令：

bash复制# 格式化
cat data.json | jq .

# 取某个字段
cat data.json | jq '.user.name'

# 按条件过滤数组
cat data.json | jq '.items[] | select(.status == "active")'

在调试JSON-RPC响应时，我往往先jq '.error'看看有没有错误对象，再jq '.result'看正常返回，非常直观。还有个细节：jq对BOM和尾逗号同样严格，报错时可以先把文件头几个字节用xxd看一眼。

对于纯离线的环境，可以准备一个离线版JSON格式化工具（很多编辑器插件内置），或者自己用Python写一个几十行的格式化脚本。关键不在于工具多高精尖，而在于你要能稳定地把“原始字符串”和“解析后的对象”切成两个清晰的心智阶段，必要时把原始字符串打印到日志里，避免带着已经解析过的对象去猜测格式问题。

5.4 结合数据库和数据处理场景的避坑清单

PostgreSQL里用jsonb时，最常见的坑是误用->和->>：->返回JSON对象类型，->>返回文本类型。在SQL里比较数字时要特别注意，比如data->>'age'得到的是字符串，与整数比较会隐式转换出意外结果。索引方面，使用@>操作符匹配路径时建议用GIN索引，否则大表查询会慢得离谱。

Spark读取JSON时另一个高频问题是Schema冲突。举个例子，一个字段在第一行是"count": 1，第十行变成"count": "1"，Spark自动推断时会把它识别成字符串，后续做数值聚合就会报错。最好的办法是在读取时显式声明Schema，或者先做一轮数据清洗统一类型。我现在接到“spark读取json”的需求，第一反应永远是“先别急着读，看看原始数据字段类型乱不乱。”

Kettle解析JSON时，路径表达式一定要在源数据样例里验证。我遇到过很多次“看起来路径对，结果全是空值”的情况，原因就是JSON数组是多层嵌套，实际路径应该是$.data.list[*].name而不是$.data.name。这个只能用样例数据反复试，没有什么捷径。

如果是用json查询函数之类的SQL函数或存储过程解析JSON，要留意字段是否存在。许多函数对缺失字段返回NULL，如果上游结构改了导致字段名拼错，你看到的只是大量的空值，而不是报错。排查这类问题，最直接的方法是先看原始JSON样本，然后逐层拆解路径。

另外一个经常出现的“小”问题是：在JSON里使用null和缺失字段的区别。两者在很多语言里的行为不一样，例如Python中data.get("key")会返回None，而data["key"]会抛异常；在JavaScript中obj.key对缺失字段返回undefined，而JSON.parse的结果里显式的null则是一个独立值。设计接口时最好明确约定，防止下游误判。

6. 这份认知对实际工程到底有什么价值

产品里那些“明明解析JSON没问题，但功能就是不工作”的案子，十有八九不是JSON语法问题，而是语义错位：把协议消息当成普通数据去解析，或者把普通数据当成协议消息去取字段。JSON-RPC里有一段数据叫error，你只看到message字段拿去显示，却没注意到code才是程序判断的分支条件，这就是忽视了协议语义。

我在给团队做技术分享时，经常用一句话收尾：JSON是语法层面的标准，JSON-RPC是语义层面的标准。 语法标准保证你能读出来，语义标准保证你知道读了之后该怎么办。实际工作中这两个层次必须分开，否则所有的调试都像是在黑箱里猜。

如果你最近也在调接口时被这些问题折磨，我建议你先把每一份收到的文本分成两个问题去问自己：第一，它是不是一段合法JSON？第二，如果是合法JSON，它在当前这个场景里是不是还承担了某种协议角色？两个问题分开排查，很多卡壳的地方会豁然开朗。

最后再分享一个我自己用着很顺手的小习惯：在代码里把“解析JSON”和“处理协议字段”拆成两个函数，一个负责parse，一个负责route。前者面对各种格式异常，后者面对各种语义错误。这样出问题时，日志一打出来就能立刻分清是JSONParseError还是ProtocolError，排查时间至少省一半。