JSON-RPC 1.0 规范 (2005)

慕容品

2023-12-01

从原始网址存档：

http://json-rpc.org/wiki/specification

JSON-RPC 1.0 规范¶

规范应为开发人员提供实现协议所需的信息。

注意： JSON -RPC 2.0 规范已经发布。

概述 ¶

JSON-RPC 是一种轻量级的远程过程调用协议。它的设计很简单！

一般机制由两个建立数据连接的对等方组成。在连接的生命周期中，对等方可以调用其他对等方提供的方法。要调用远程方法，需要发送一个请求。除非请求是通知，否则必须用响应来回复。

1.1 请求（方法调用）¶

通过向远程服务发送请求来调用远程方法。该请求是使用JSON序列化的单个对象。

它具有三个属性：

method - 一个字符串，包含要调用的方法的名称。
params - 要作为参数传递给方法的对象数组。
id - 请求 ID。这可以是任何类型。它用于将响应与它正在回复的请求相匹配。

1.2 响应¶

当方法调用完成时，服务必须回复一个响应。响应是使用JSON序列化的单个对象。

它具有三个属性：

result - 被调用方法返回的对象。如果调用该方法时出错，这必须为 null。
error - 如果调用该方法时出错，则返回一个 Error 对象。如果没有错误，它必须为 null。
id - 这必须与它响应的请求相同。

1.3 通知¶

通知是没有响应的特殊请求。通知是使用JSON序列化的单个对象。

它具有与请求对象相同的属性，但有一个例外。

id - 必须为空。

2.1 流连接上的 JSON-RPC ¶

规范不需要特定的传输协议。鼓励使用 TCP/IP 套接字流。序列化的请求和响应对象通过字节流发送给对等方。

请求和响应可以随时发送到对等点。对等方必须响应每个请求，除非它是一个通知。响应只能作为对请求的回复而发送。

关闭对等点之间的连接必须为每个对等点上的所有未应答请求引发异常。无效的请求或响应必须导致关闭连接。

2.2 基于 HTTP 的 JSON-RPC ¶

有一些限制，HTTP 请求可以用作对等点之间通信的传输。

对等点之间的通信，一个是 HTTP 客户端，另一个是 HTTP 服务器，可能跨越多个 HTTP 请求。客户端对等点可以通过发送包含所有序列化对象的 HTTP POST 请求向其对等点发送一个或多个请求、通知或响应。

服务器端对等点必须对所有发送的请求做出响应，并且可以发送自己的请求或通知。客户端对等方必须回复通过发送另一个 HTTP POST 接收到的请求。

为了让服务器端对等点有机会向客户端对等点发送消息，客户端对等点可以通过发送空的 HTTP POST 重新打开通信。

无效的请求必须导致关闭连接。无效响应必须为客户端上所有未响应的请求引发异常。关闭连接必须为客户端上所有未应答的请求引发异常。

FIXME：描述/定义如何处理会话，因为没有由 TCP 连接形成的隐式会话。

3. JSON 类提示¶

JSON 中只定义了简单的数据类型。为了以兼容 JSON 的方式克服这个问题，引入了对象的特殊属性。

{"__jsonclass__":["constructor", [param1,...]], "prop1": ...}

然后使用构造函数实例化对象，并传入参数。构建后，将应用属性 (prop1, ...)。

4. 通信示例¶

--> 发送到服务
的数据 <-- 来自服务的数据

service.echo("Hello JSON-RPC")

--> { "method": "echo", "params": ["Hello JSON-RPC"], "id":
1}
<-- { "result": "Hello JSON-RPC", "error": null, "id": 1}

多个请求响应

此示例显示来自示例聊天应用程序的部分通信。聊天服务为客户端应接收的每条聊天消息发送通知。客户端对等端发送请求以将消息发布到聊天中，并期望得到肯定的答复以知道消息已发布。

...

--> {"method": "postMessage", "params": ["Hello all!"], "id": 99}
<-- {"result": 1, "error": null, "id": 99}
<-- {"method": "handleMessage", "params": ["user1", "we were just talking"], "id":
null}
<-- {"method": "handleMessage", "params": ["user3", "sorry, gotta go now, ttyl"], "id":
null}
--> {"method": "postMessage", "params": ["I have a question:"], "id": 101}
<-- {"method": "userLeft", "params": ["user3"], "id": null}
<-- {"result": 1, "error": null, "id": 101}
...

上面授予的有限权限是永久的，不会被 JSON-RPC.org 撤销。

本文档和此处包含的信息按“原样”提供，json-rpc.org 不提供任何明示或暗示的保证，包括但不限于使用此处信息不会侵犯任何权利或对适销性或特定用途适用性的任何默示保证。