通信协议jsonrpc

JSON-RPC是一种轻量级且无状态的远程过程调用（RPC）协议，它使用JSON（JavaScript Object Notation）作为数据格式，并通过HTTP或TCP协议传输数据。它允许客户端和服务器之间进行无状态的通信，从而实现分布式应用程序的远程过程调用。

JSON-RPC特性

JSON-RPC具有以下特性：

1. 简单易用：JSON-RPC使用简单的语法和数据格式，易于使用和理解。

2. 轻量级：JSON-RPC使用轻量级的数据格式，传输数据量小，网络传输速度快。

3. 跨平台：JSON-RPC可以在不同的平台和语言之间进行通信，包括Java、Python、JavaScript、Ruby等。

4. 可扩展性：JSON-RPC可以通过添加自定义的方法和参数来扩展协议，以满足不同的应用程序需求。

JSON-RPC的原理是基于HTTP或TCP协议，客户端向服务器发送一个包含方法名和参数的JSON请求，服务器返回一个包含结果或错误信息的JSON响应。

JSON-RPC规范

请求

发送一个请求对象至服务端代表一个RPC调用，请求和响应都遵循一定的格式规范，一个请求对象包含下列成员：

请求格式：

{
    "jsonrpc": "2.0",
    "method": "add",
    "params": [1, 2],
    "id": 1
}

响应

当发起一个rpc调用时，除通知之外，服务端都必须回复响应。响应表示为一个JSON对象

服务端必须回答相同的值包含在响应对象。这个成员用来两个对象之间的关联上下文。在请求对象中不建议使用 NULL 作为 id 值，因为该规范将使用空值认定为未知id的请求。另外，由于JSON-RPC 1.0 的通知使用了空值，这可能引起处理上的混淆。使用小数是不确定性的，因为许多十进制小数不能精准的表达为二进制小数。

响应格式：

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

其中

• jsonrpc

表示协议版本号，指定JSON-RPC协议版本的字符串，必须准确写为“2.0”；

• method

表示调用的方法名；

• params

表示传递的参数；

• id

表示请求的唯一标识符，用于匹配请求和响应。

该成员必须包含。

该成员值必须于请求对象中的id成员值一致。

若在检查请求对象id时错误（例如参数错误或无效请求），则该值必须为空值。

• result

    该成员在成功时必须包含。

    当调用方法引起错误时必须不包含该成员。

服务端中的被调用方法决定了该成员的值。

• error

    该成员在失败是必须包含。

    当没有引起错误的时必须不包含该成员。

    该成员参数值必须为5.1中定义的对象。

响应对象必须包含result或error成员，但两个成员必须不能同时包含。

在JSON-RPC中，客户端和服务器之间的通信是无状态的，每个请求都是独立的，服务器不会保存任何状态信息。这种设计使得JSON-RPC更加简单和可扩展，同时也需要应用程序自行处理状态信息。

错误对象

当一个rpc调用遇到错误时，返回的响应对象必须包含错误成员参数，并且为带有下列成员参数的对象：

• code

    使用数值表示该异常的错误类型。 必须为整数。

• message

    对该错误的简单描述字符串。 该描述应尽量限定在简短的一句话。

• data

    包含关于错误附加信息的基本类型或结构化类型。该成员可忽略。 该成员值由服务端定义（例如详细的错误信息，嵌套的错误等）。

-32768至-32000为保留的预定义错误代码。在该范围内的错误代码不能被明确定义，保留下列以供将来使用。错误代码基本与XML-RPC建议的一样

批量调用

当需要同时发送多个请求对象时，客户端可以发送一个包含所有请求对象的数组。

当批量调用的所有请求对象处理完成时，服务端则需要返回一个包含相对应的响应对象数组。每个响应对象都应对应每个请求对象，除非是通知的请求对象。服务端可以并发的，以任意顺序和任意宽度的并行性来处理这些批量调用。

这些相应的响应对象可以任意顺序的包含在返回的数组中，而客户端应该是基于各个响应对象中的 id 成员来匹配对应的请求对象。

若批量调用的 RPC 操作本身非一个有效JSON或一个至少包含一个值的数组，则服务端返回的将单单是一个响应对象而非数组。若批量调用没有需要返回的响应对象，则服务端不需要返回任何结果且必须不能返回一个空数组给客户端。

示例

带索引数组参数的rpc调用

--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

--> {"jsonrpc": "2.0", "method": "subtract", "params": [23, 42], "id": 2}
<-- {"jsonrpc": "2.0", "result": -19, "id": 2}

无效的rpc批量调用

--> [1,2,3]
<-- [
    {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
    {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
    {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}
    ]

rpc批量调用

--> [
    {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
    {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
    {"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
    {"foo": "boo"},
    {"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"},
    {"jsonrpc": "2.0", "method": "get_data", "id": "9"}
    ]
<-- [
    {"jsonrpc": "2.0", "result": 7, "id": "1"},
    {"jsonrpc": "2.0", "result": 19, "id": "2"},
    {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
    {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "5"},
    {"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
    ]

扩展

以rpc开头的方法名预留作为系统扩展，且必须不能用于其他地方。每个系统扩展都应该有相关规范文档，所有系统扩展都应是可选的。

总之，JSON-RPC是一种简单、轻量级、跨平台、可扩展的RPC协议，它可以帮助开发者实现分布式应用程序的远程过程调用。

---

最新文章首发 · 微信公众号搜索【CTO Plus】关注后，获取更多，我们一起学习交流。

---