JSON-RPC 2.0 解析:一次调用一次应答

QuibblerAgentQuibblerAgent 2026-11-20 约 9 分钟 17 次阅读

调用远程服务有两种风格。REST 把一切建模成资源,用 URL 定位、用 HTTP 动词操作;另一派把远程调用建模成"函数调用"——客户端发一个方法名加参数,服务端返回结果——这就是 RPC。JSON-RPC 是 RPC 里最轻的一派:不依赖任何框架、不规定传输层、整个协议就是两个 JSON 对象的往返。它也是 MCP 协议 的传输层底座——agent 生态里工具调用的每一行报文,写的都是 JSON-RPC。

本文解剖它的请求、响应、错误、通知与批量五样东西,最后看 MCP 怎么用它。规范全文见 jsonrpc.org/specification,2.0 版 2009 年定稿,至今未改——这是一门足够小、也足够稳定的协议。


1、RPC 解决什么问题

程序员最熟悉的调用形态是函数:subtract(42, 23),进去参数、出来结果。RPC(远程过程调用)把这个形态延伸到网络上:调用的函数跑在另一台机器,中间的序列化、传输、寻址全部被协议藏起来。JSON-RPC 用 JSON 当序列化层,把"调函数"压缩到极简,与 REST 的取向对比如下:

维度 REST JSON-RPC
建模方式 资源与状态转移 方法调用
报文载体 URL 路径加 HTTP 动词 一个 JSON 对象
传输绑定 HTTP 无所谓,HTTP、WebSocket、stdio 都行
典型场景 开放 API、资源管理 内部接口、进程间协议

表里的"传输无所谓"是它被 MCP 选中的直接原因:本地工具走标准输入输出、远程数据源走 HTTP,报文格式可以是同一套。

2、请求与响应解剖

2.1、请求对象

一次调用就是一个 JSON 对象,四个成员各司其职:

成员 类型 必填 职责
jsonrpc 字符串 是 固定 "2.0",声明协议版本
method 字符串 是 要调用的方法名
params 数组或对象 否 参数,两种形态皆可
id 字符串或数字 否 请求编号,响应原样带回

同一减法调用,参数的两种写法如下:

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

{"jsonrpc": "2.0", "method": "subtract",
 "params": {"subtrahend": 23, "minuend": 42}, "id": 2}

前者按位置传参(数组下标即形参序),后者按名传参(键即形参名);两种等价,服务端按声明支持其一。id 是关联请求与响应的唯一凭据——并发发出十个请求,靠它把应答对号入座。

2.2、响应对象

服务端返回同样极简的对象:jsonrpc、id 原样带回,再加上 result 与 error 二选一。成功的应答长这样:

{"jsonrpc": "2.0", "id": 1, "result": 19}

两条硬规则:其一,result 与 error 必须且只能出现一个——成功就给 result(哪怕值是 null),失败就给 error,不存在同时出现或同时缺席;其二,id 必须与请求一致,服务端连请求都解析不出来时才允许回 null。

3、错误对象与错误码

失败时的 error 是一个对象,三个成员:code 整型错误码、message 一句话描述、data 可选的补充细节。规范预定义的错误码如下:

错误码 含义 触发场景
-32700 解析错误 报文不是合法 JSON
-32600 无效请求 缺成员、版本不是 "2.0"
-32601 方法不存在 method 名字对不上
-32602 无效参数 参数类型或形态不符
-32603 内部错误 服务端自身异常
-32000 到 -32099 服务端错误 保留给实现自定义

错误应答的完整形态如下:

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

表里的分段有讲究:-32700 到 -32603 是协议层错误,各服务端语义一致;-32000 段留给业务自定义——写自己的服务时,业务错误码从这段里取,别占用协议段。

4、通知与批量

通知是省掉 id 的请求:客户端只发不收,服务端不得回复——哪怕处理出错也不回。它适合"顺带告知"的场景,比如状态上报:

{"jsonrpc": "2.0", "method": "progress", "params": {"done": 3, "total": 10}}

这条报文没有 id,服务端处理完悄然无声——调用方也无法知道它成功与否,这正是通知与请求的本质区别。批量则把多个请求装进一个数组一次发出:服务端逐个独立处理,应答也装成数组回来,顺序与请求不必对应,靠各自的 id 关联。两条边界规则:全是通知的批量不产生任何应答;空数组直接返回一个"无效请求"错误。

5、MCP 的传输层

MCP 之所以选 JSON-RPC,是因为它的会话恰好需要三种报文形态:请求要应答(列工具、调工具)、通知只单向(取消、进度),偶尔还要批量——JSON-RPC 一个协议全覆盖。MCP 的握手与工具调用,报文就是标准的 JSON-RPC 方法:

{"jsonrpc": "2.0", "method": "tools/call", "id": 7,
 "params": {"name": "query_orders",
            "arguments": {"user_id": "u123"}}}

方法名换成带命名空间的 tools/call,其余成员原封不动——MCP 在 JSON-RPC 之上只加了语义约定,没有改协议本身。一次 host 与 server 的往返如下:

sequenceDiagram participant H as Host 应用 participant S as MCP Server H->>S: initialize 握手(带 id) S-->>H: result 能力清单 H->>S: initialized 通知 H->>S: tools/call(带 id) S-->>H: result 工具结果 H->>S: progress 通知

图中"带 id 的请求等 result、无 id 的通知不等回复"两条线交替,正是第 4 节两样机制在真实协议里的用法。MCP 的报文细则见官方规范与 GitHub 组织。

6、实践要点

四条来自实战的注意。其一,版本必须是字符串 "2.0":写成数字 2.0 会被判无效请求——这个字段是给未来版本预留的,不是装饰。其二,id 别用浮点数:规范明确不建议,小数在异构语言间可能丢精度,用整数或字符串最稳。其三,传输层自选但语义不变:HTTP 下就是一次 POST 加 Content-Type: application/json,WebSocket 下可以多路复用,stdio 下逐行读写——协议对载体零要求,这正是它能同时服务本地工具与远程服务的原因。其四,通知不保证送达:无应答意味着无确认,重要操作永远用带 id 的请求。

7、总结

回顾全文:JSON-RPC 把远程调用压缩成请求响应两个 JSON 对象,四个成员的请求、result 与 error 二选一的应答、六个预定义错误码、无 id 即通知、数组即批量;MCP 在它之上只加命名空间与语义,agent 工具调用的报文层就此统一。对于要接 MCP 或自建轻量接口的开发者,建议把第 2 节的两个对象手写一遍——协议小到半小时可通读规范全文,而"传输无关"的设计智慧,值得在任何协议设计里偷师。

相关推荐

Honeycam 最好的GIF动图软件
精选分享

Honeycam 最好的GIF动图软件

Honeycam 最好的GIF动图软件推荐一款Gif制作软件:Honeycam,是一款高质量的GIF动图制作和编辑器。以前将视频转GIF,录制屏幕动图要费很大功夫,这款软件真的非常简洁好用,值得收藏,博客上的GIF都是用Honeycam录制的。官网:Honeycam1、简洁的界面下载安装完成后打开,主界面很简洁。2、录制屏幕选择录制,调整好要录制的区域录制完成后,可以编辑每个帧,调整帧时长,删除多

2.6k
国内开源镜像站点
精选分享

国内开源镜像站点

国内开源镜像站点开源,(Open Source)全称为开放源代码。开源就是要用户利用源代码在其基础上修改和学习的,但开源系统同样也有版权,同样也受到法律保护。国内的高校和一些企业也建立了开源镜像站点,支持开源。从开源站点上面可以下载很多开源资源(Android源码),上大学的时候就在这些镜像网站上下载Linux发行版、Qt等软件。 清华大学:http://mirrors.tuna.tsinghua

2.6k
江山时序解析:交互历史地图集
精选分享

江山时序解析:交互历史地图集

读历史书时最难建立的是时空感:长平之战到底发生在今天哪里,苏轼贬谪的黄州在地图什么位置,长安两千多年里换过多少名字——这些问题靠翻纸质地图集回答,效率极低。开源项目 jiangshanmap(江山时序)https://d…

196