RPC、JSON-RPC 1.0、JSON-RPC 2.0 与 RESTful 使用笔记

同一个远程调用，既可以写成 Add(10, 20) 这样的方法调用，也可以写成 GET /tasks/1001 这样的资源请求。下面从 RPC 思想出发，依次看 JSON-RPC 1.0、2.0 和 RESTful 各自如何表达一次操作，最后看 A2A 如何在 JSON-RPC 之上定义 Agent 间的方法。

1. RPC 是什么？#

RPC（Remote Procedure Call，远程过程调用）是一种通信思想：调用远程机器上的函数，就像调用本地函数一样。

例如，客户端想让服务端计算 10 + 20：

1
result := Add(10, 20)

实际过程：

客户端将函数名 Add 和参数 10、20 序列化。
通过网络发送给服务端。
服务端找到对应的 Add 函数并执行。
服务端将结果返回。
客户端拿到结果。

RPC 本身不规定必须使用 HTTP，也不规定必须使用 JSON。

常见 RPC 技术：

JSON-RPC
gRPC
XML-RPC
Apache Thrift

核心：RPC 关注的是远程调用函数或方法。

2. JSON-RPC 1.0#

JSON-RPC 是 RPC 的一种实现方式，使用 JSON 格式传递请求和响应。

2.1 怎么调用？#

假设服务端提供了一个 add 方法，客户端想计算 10 + 20。

客户端发送：

1
{
2
  "method": "add",
3
  "params": [10, 20],
4
  "id": 1
5
}

服务端返回：

1
{
2
  "result": 30,
3
  "error": null,
4
  "id": 1
5
}

字段含义：

字段	作用
method	要调用的方法
params	方法参数
id	请求标识，用于匹配响应
result	调用成功后的结果
error	调用失败时的错误信息

2.2 再看一个实际例子#

假设服务端提供了用户查询方法：

请求：

1
{
2
  "method": "getUser",
3
  "params": [1001],
4
  "id": 2
5
}

响应：

1
{
2
  "result": {
3
    "id": 1001,
4
    "name": "Tom"
5
  },
6
  "error": null,
7
  "id": 2
8
}

这里相当于调用远程的：

1
user := getUser(1001)

2.3 JSON-RPC 1.0 的特点#

使用 method 指定调用的方法。
使用 params 传递参数，通常是数组。
使用 id 关联请求和响应。
没有 jsonrpc 版本字段。
通知请求使用 id: null，服务端不返回响应。

3. JSON-RPC 2.0#

JSON-RPC 2.0 是 JSON-RPC 的后续版本，规范更加明确。

3.1 怎么调用？#

还是计算 10 + 20。

请求：

1
{
2
  "jsonrpc": "2.0",
3
  "method": "add",
4
  "params": [10, 20],
5
  "id": 1
6
}

响应：

1
{
2
  "jsonrpc": "2.0",
3
  "result": 30,
4
  "id": 1
5
}

和 1.0 相比，最明显的变化是增加了：

1
"jsonrpc": "2.0"

3.2 支持命名参数#

JSON-RPC 2.0 的 params 不仅可以使用数组，还可以使用对象。

数组参数：

1
{
2
  "jsonrpc": "2.0",
3
  "method": "add",
4
  "params": [10, 20],
5
  "id": 1
6
}

对象参数：

1
{
2
  "jsonrpc": "2.0",
3
  "method": "add",
4
  "params": {
5
    "a": 10,
6
    "b": 20
7
  },
8
  "id": 1
9
}

对象参数的好处是可读性更好，也不容易搞错参数顺序。

3.3 错误响应#

例如，客户端调用了一个不存在的方法：

1
{
2
  "jsonrpc": "2.0",
3
  "method": "unknownMethod",
4
  "id": 1
5
}

服务端返回：

1
{
2
  "jsonrpc": "2.0",
3
  "error": {
4
    "code": -32601,
5
    "message": "Method not found"
6
  },
7
  "id": 1
8
}

常见错误码：

错误码	含义
-32700	JSON 解析错误
-32600	无效请求
-32601	方法不存在
-32602	参数无效
-32603	内部错误

3.4 通知 Notification#

如果客户端只想通知服务端做一件事，不需要等待结果，可以发送通知。

1
{
2
  "jsonrpc": "2.0",
3
  "method": "logEvent",
4
  "params": {
5
    "event": "user_login"
6
  }
7
}

NOTE
这里没有 id。

服务端收到通知后执行操作，但不返回 JSON-RPC 响应。

3.5 批量请求 Batch#

JSON-RPC 2.0 支持一次发送多个请求：

1
[
2
  {
3
    "jsonrpc": "2.0",
4
    "method": "getUser",
5
    "params": [1001],
6
    "id": 1
7
  },
8
  {
9
    "jsonrpc": "2.0",
10
    "method": "getUser",
11
    "params": [1002],
12
    "id": 2
13
  }
14
]

服务端可以返回多个响应：

1
[
2
  {
3
    "jsonrpc": "2.0",
4
    "result": {"id": 1001, "name": "Tom"},
5
    "id": 1
6
  },
7
  {
8
    "jsonrpc": "2.0",
9
    "result": {"id": 1002, "name": "Jack"},
10
    "id": 2
11
  }
12
]

响应顺序不一定与请求顺序一致，需要通过 id 匹配。

3.6 JSON-RPC 2.0 的特点#

必须带有 jsonrpc: "2.0"。
method 指定调用的方法。
params 支持数组和对象。
id 用于关联请求与响应。
通知请求省略 id。
支持批量请求。
成功响应使用 result，失败响应使用 error，两者不能同时出现。

4. RESTful API#

RESTful 和 JSON-RPC 不一样。

JSON-RPC 是通过方法名来指定操作，而 RESTful 是围绕资源设计 API，通常结合 HTTP 方法表达操作。

例如，我们有一个任务管理服务，资源是 tasks。

4.1 查询任务#

1
GET /tasks/1001

含义：获取 ID 为 1001 的任务。

响应：

1
{
2
  "id": 1001,
3
  "name": "Build project",
4
  "status": "running"
5
}

4.2 创建任务#

1
POST /tasks
2
Content-Type: application/json

请求体：

1
{
2
  "name": "Build project"
3
}

含义：创建一个任务。

4.3 修改任务#

整体替换：

1
PUT /tasks/1001

部分修改：

1
PATCH /tasks/1001
2
Content-Type: application/json

请求体：

1
{
2
  "status": "completed"
3
}

4.4 删除任务#

1
DELETE /tasks/1001

含义：删除 ID 为 1001 的任务。

4.5 RESTful 常用 HTTP 方法#

HTTP 方法	常见用途
GET	查询资源
POST	创建资源或执行某些操作
PUT	整体替换资源
PATCH	部分修改资源
DELETE	删除资源

RESTful 是一种 API 架构风格，并不强制使用 JSON，JSON 只是常见的数据格式。

5. JSON-RPC 和 RESTful 的区别#

假设现在要查询一个任务。

JSON-RPC 2.0#

请求：

1
POST /rpc
2
Content-Type: application/json

请求体：

1
{
2
  "jsonrpc": "2.0",
3
  "method": "tasks/get",
4
  "params": {
5
    "taskId": "1001"
6
  },
7
  "id": 1
8
}

RESTful#

请求：

1
GET /tasks/1001

两者都能完成查询任务，但表达方式不同。

对比	JSON-RPC 2.0	RESTful
核心思路	调用方法	操作资源
操作标识	method	HTTP Method + URL
参数位置	params	URL、Query、Body
常见请求	POST	GET、POST、PUT、PATCH、DELETE
数据格式	JSON	不限，常用 JSON
典型场景	远程方法调用、协议交互	Web API、资源管理

记住：

JSON-RPC：我要调用哪个方法？
RESTful：我要操作哪个资源？

6. A2A 中的 JSON-RPC 是怎么用的？#

A2A（Agent2Agent Protocol）使用 JSON-RPC 2.0 作为一种常见的通信绑定。

假设 Agent A 想让 Agent B 执行一个任务。

6.1 提交任务：message/send#

Agent A 向 Agent B 发送：

1
POST /a2a
2
Content-Type: application/json

请求体：

1
{
2
  "jsonrpc": "2.0",
3
  "method": "message/send",
4
  "params": {
5
    "message": {
6
      "role": "user",
7
      "parts": [
8
        {
9
          "kind": "text",
10
          "text": "帮我分析这个项目的架构"
11
        }
12
      ]
13
    }
14
  },
15
  "id": 1
16
}

这里：

HTTP POST：负责把请求发送到 Agent B。
method：告诉 Agent B 要执行 message/send。
params：携带消息内容。
id：标识本次 JSON-RPC 请求。

6.2 查询任务：tasks/get#

如果任务还没有完成，可以查询任务状态：

1
{
2
  "jsonrpc": "2.0",
3
  "method": "tasks/get",
4
  "params": {
5
    "id": "task-001"
6
  },
7
  "id": 2
8
}

Agent B 返回任务状态，例如：

1
{
2
  "jsonrpc": "2.0",
3
  "result": {
4
    "id": "task-001",
5
    "status": {
6
      "state": "working"
7
    }
8
  },
9
  "id": 2
10
}

6.3 流式获取进度：message/stream#

如果希望实时接收 Agent B 的任务进度，可以使用：

1
{
2
  "jsonrpc": "2.0",
3
  "method": "message/stream",
4
  "params": {
5
    "message": {
6
      "role": "user",
7
      "parts": [
8
        {
9
          "kind": "text",
10
          "text": "分析项目架构"
11
        }
12
      ]
13
    }
14
  },
15
  "id": 3
16
}

在 HTTP+JSON-RPC 绑定中，服务端可以通过 SSE（Server-Sent Events）持续推送事件。

6.4 常见 A2A 方法#

方法	用途
message/send	发送消息或提交任务
message/stream	发送消息并流式接收事件
tasks/get	查询任务状态
tasks/cancel	取消任务
tasks/resubscribe	重新订阅任务事件
tasks/pushNotificationConfig/set	设置任务推送配置

WARNING
message/send、tasks/get 等是 JSON-RPC 的 method 名称，不是 HTTP 的 GET、POST 方法。

7. 最后总结#

名称	你应该怎么理解
RPC	远程调用函数的一种思想
JSON-RPC 1.0	使用 JSON 表达远程方法调用
JSON-RPC 2.0	增加版本标识、命名参数、通知和批量请求等规范
RESTful	通过资源 URL 和 HTTP 方法设计 API
HTTP	网络传输协议，定义 GET、POST 等请求方法

一句话记忆#

RPC：远程调用函数。
JSON-RPC：通过 JSON 传递方法名和参数。
RESTful：通过 URL 和 HTTP 方法操作资源。
HTTP GET/POST：HTTP 层的请求方法。
JSON-RPC method：JSON-RPC 层的操作名称。

最重要的区别：

1
RESTful：
2
GET /tasks/1001
3

4
JSON-RPC：
5
POST /rpc
6
{
7
  "jsonrpc": "2.0",
8
  "method": "tasks/get",
9
  "params": {
10
    "id": "1001"
11
  },
12
  "id": 1
13
}

前者通过 HTTP 方法和 URL 表达操作；后者通过 JSON-RPC 请求体中的 method 表达操作。