当前位置：首页 > news >正文

理解JSON-RPC 2.0 协议

news 来源：原创 2025/6/18 12:33:28

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 规范的完整交互示例，包含请求、成功响应和错误响应三种典型场景：

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

// 服务端成功响应
{
  "jsonrpc": "2.0",
  "result": {
    "userId": 12345,
    "name": "张三",
    "email": "zhangsan@example.com",
    "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"
}

扩展场景示例：

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

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

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

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

批处理请求

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