1.JSON-RPC 协议规范 #

JSON-RPC（JavaScript Object Notation Remote Procedure Call） 是一种轻量级的远程过程调用（RPC）协议，使用 JSON（JavaScript Object Notation） 作为数据交换格式。它允许客户端向服务器发送请求并获取响应，支持 无状态 和 双向通信（如 WebSocket）。

2. JSON-RPC 核心特点 #

简单易用：基于 JSON，易于解析和生成。
语言无关：任何支持 JSON 的语言均可实现。
轻量级：相比 SOAP、gRPC 等协议，数据量更小。
支持通知（Notification）：客户端可以发送不需要响应的请求。
支持批量请求（Batch）：一次发送多个请求。

3. JSON-RPC 版本 #

目前主要有 2 个版本：

• JSON-RPC 1.0（2005）
  • 无严格规范，部分实现可能不兼容。
  • 使用 method、params、id 字段。
• JSON-RPC 2.0（2010，主流版本）
  • 标准化（官方规范）。
  • 新增 jsonrpc: "2.0" 字段标识版本。
  • 支持 命名参数（Named Parameters） 和 位置参数（Positional Parameters）。
  • 更清晰的 错误处理（定义标准错误码）。

4. JSON-RPC 2.0 数据结构 #

(1) 请求（Request） #

客户端向服务器发送的 JSON 数据格式：

{
  "jsonrpc": "2.0",  // 必须，标识协议版本
  "method": "subtract",  // 必须，调用的方法名
  "params": [42, 23],   // 可选，参数（数组或对象）
  "id": 1               // 可选，请求 ID（用于匹配响应）
}

• params 可以是：
  • 位置参数（数组）："params": [42, 23]
  • 命名参数（对象）："params": {"a": 42, "b": 23}
• id 的作用：
  • 如果存在，服务器必须返回响应。
  • 如果 id 为 null，表示 通知（Notification），服务器不返回响应。

(2) 响应（Response） #

服务器返回的 JSON 数据格式：

成功响应 #

{
  "jsonrpc": "2.0",
  "result": 19,   // 必须，方法返回值
  "id": 1         // 必须，与请求的 id 一致
}

错误响应 #

{
  "jsonrpc": "2.0",
  "error": {       // 必须，错误信息
    "code": -32601,
    "message": "Method not found",
    "data": null   // 可选，额外错误数据
  },
  "id": 1          // 必须，与请求的 id 一致
}

• 标准错误码（部分）：

错误码	含义
-32700	解析错误（Invalid JSON）
-32600	无效请求（Invalid Request）
-32601	方法不存在（Method not found）
-32602	无效参数（Invalid params）
-32603	内部错误（Internal error）
-32000 ~ -32099	服务器自定义错误

(3) 通知（Notification） #

客户端发送 不需要响应 的请求（id 为 null）：

{
  "jsonrpc": "2.0",
  "method": "update",
  "params": [1, 2, 3],
  "id": null  // 表示通知，服务器不返回响应
}

(4) 批量请求（Batch） #

客户端可以一次发送多个请求（数组形式）：

[
  {"jsonrpc": "2.0", "method": "sum", "params": [1, 2], "id": 1},
  {"jsonrpc": "2.0", "method": "notify", "params": ["hello"], "id": null},
  {"jsonrpc": "2.0", "method": "getData", "id": 2}
]

服务器返回 批量响应（按请求顺序返回）：

[
  {"jsonrpc": "2.0", "result": 3, "id": 1},
  {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": 2}
]
// 通知（notify）没有响应

5. 传输方式 #

JSON-RPC 不限定传输层，可以基于：

• HTTP（最常见）
• WebSocket（双向通信）
• TCP/UDP（自定义协议）
• 消息队列（MQTT、RabbitMQ）

HTTP 示例（POST 请求） #

请求：

POST /rpc HTTP/1.1
Content-Type: application/json

{"jsonrpc": "2.0", "method": "echo", "params": ["Hello"], "id": 1}

响应：

HTTP/1.1 200 OK
Content-Type: application/json

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

6. 对比其他 RPC 协议 #

特性	JSON-RPC	REST	gRPC	SOAP
数据格式	JSON	JSON/XML	Protobuf	XML
协议层	应用层	HTTP	HTTP/2	HTTP
性能	中	低	高	低
适用场景	简单 RPC	资源操作	高性能微服务	企业级服务

7. 实现示例（Python） #

服务端（Python + Flask） #

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/rpc', methods=['POST'])
def rpc():
    req = request.json
    if req["method"] == "subtract":
        a, b = req["params"]
        return jsonify({"jsonrpc": "2.0", "result": a - b, "id": req["id"]})
    else:
        return jsonify({"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": req["id"]})

if __name__ == '__main__':
    app.run()

客户端（Python requests） #

import requests

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

response = requests.post("http://localhost:5000/rpc", json=payload).json()
print(response["result"])  # 输出 19

8. 常见应用 #

• 以太坊（Ethereum） 的 API 使用 JSON-RPC。
• Bitcoin Core 提供 JSON-RPC 接口。
• VS Code 插件通信 使用 JSON-RPC。
• 微服务间通信（替代 REST）。

9. 总结 #

要点	说明
协议版本	推荐 JSON-RPC 2.0（标准化）
请求结构	method, params, id
响应结构	result 或 error
传输方式	HTTP、WebSocket、TCP 等
适用场景	轻量级 RPC，跨语言调用

JSON-RPC 是一种 简单、灵活、跨语言 的 RPC 协议，适用于 前后端通信、区块链、微服务 等场景。