理解JSON-RPC 2.0 协议

JSON-RPC 2.0是指一种基于 JSON 的远程过程调用协议，用于在网络上进行跨平台和跨语言的通信。它提供了一种简单、轻量级的方式来实现客户端和服务器之间的方法调用和数据交换。在原文中，JSON-RPC 2.0被用来描述 STDIO 传输机制中消息的格式，即客户端通过标准输入输出流与服务器通信时，消息是按照 JSON-RPC 2.0 的规范进行编码的。

JSON-RPC 2.0的具体含义包括：

它是一种无状态的轻量级 RPC 协议，使用 JSON 作为数据交换格式。
请求和响应都必须包含 jsonrpc 字段，其值为 "2.0"，以指明使用的协议版本。
请求必须包含 method 字段，表示要调用的方法名。
请求可以包含 params 字段，用于传递调用方法的参数。
请求可以包含 id 字段，用于关联请求和响应，但通知类型请求可以省略 id。
响应必须包含 jsonrpc 字段，值为 "2.0"，以及 id 字段，以便客户端知道哪个请求得到了响应。
成功的响应包含 result 字段，用于返回方法调用的结果。
错误响应包含 error 字段，用于描述错误信息，包括错误代码、错误消息和可选的额外数据。

JSON-RPC 2.0在智能体通信协议MCP中被采用，作为其传输层的一部分，使得AI模型能够通过统一的标准接口与外部数据源和工具进行交互。这不仅简化了集成过程，还提高了灵活性和扩展性。

以下是一个符合 JSON-RPC 2.0 规范的完整交互示例，包含请求、成功响应和错误响应三种典型场景：

json 复制代码

// 客户端请求（位置参数版本）
{
  "jsonrpc": "2.0",
  "method": "getUserInfo",
  "params": [12345],
  "id": "req_20250409_001"
}

// 服务端成功响应
{
  "jsonrpc": "2.0",
  "result": {
    "userId": 12345,
    "name": "张三",
    "email": "[email protected]",
    "registrationDate": "2024-03-15"
  },
  "id": "req_20250409_001"
}

// 服务端错误响应（当用户不存在时）
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "User ID does not exist"
  },
  "id": "req_20250409_001"
}

扩展场景示例：

命名参数调用（更适合复杂参数）

bash 复制代码

// 带命名参数的请求
{
  "jsonrpc": "2.0",
  "method": "calculateDistance",
  "params": {
    "start": {"lat": 31.2304, "lng": 121.4737},
    "end": {"lat": 39.9042, "lng": 116.4074}
  },
  "id": "geo_001"
}

通知型请求（不需要响应）

json 复制代码

// 服务端不会返回响应的通知
{
  "jsonrpc": "2.0",
  "method": "logEvent",
  "params": {
    "eventType": "user_login",
    "timestamp": "2025-04-09T14:30:00Z"
  }
}

批处理请求

json 复制代码

// 同时发送两个查询请求
[
  {"jsonrpc":"2.0","method":"getStockPrice","params":["AAPL"],"id":"stock_1"},
  {"jsonrpc":"2.0","method":"getWeather","params":["Shanghai"],"id":"weather_1"}
]

协议特性说明：

必选字段：所有消息必须包含 "jsonrpc": "2.0"

错误代码规范：

-32700 解析错误（Parse error）
-32600 无效请求（Invalid Request）
-32601 方法未找到（Method not found）
-32602 无效参数（Invalid params）

应用级错误建议使用 -32000 至 -32099 范围

参数传递支持两种形式：有序数组（适用于位置参数）或键值对对象（适用于命名参数）。

实际应用中，该协议常用于：

浏览器插件与宿主程序通信
微服务间的轻量级交互
IDE 与语言服务器的通信（如VSCode的LSP协议）
IoT设备控制指令传输