轻量级通信协议 JSON-RPC 2.0 详解
目录
JSON-RPC 2.0 简介
请求对象
响应对象
通知
批量请求
错误码
使用场景
文档和版本控制
社区和支持
小结
参考资料
JSON-RPC 2.0 简介
JSON-RPC (JavaScript Object Notation - Remote Procedure Call) 是一种轻量级的远程过程调用协议，使用 JSON（JavaScript 对象表示法）作为数据格式。JSON-RPC 2.0 是该协议的最新版本，在 1.0 版本的基础上增加了一些特性，如错误代码标准化、批量请求支持和无响应的通知。
JSON-RPC 的设计原则是简单性和互操作性，旨在为不同编程语言之间提供一种方便的方法来执行远程过程调用。通过定义一组简单的规则，任何能够解析 JSON 的语言或平台都可以实现 JSON-RPC 客户端或服务器。
接下来看下 JSON-RPC 2.0 协议的规范。
请求对象
一个 JSON-RPC 2.0 请求数据是一个单一的 JSON 对象，可以包含以下成员：
- jsonrpc：字符串，指定 JSON-RPC 的版本号，对于 2.0 规范来说，这个值必须是 2.0。
- method：字符串，指定要调用的远程方法的名称。
- params：结构化值，可以是数组或者对象，传递给远程方法的参数。如果方法不需要参数可以省略。
- id：唯一标识符，可以是字符串或数字，用于关联请求和响应，服务端必须返回相同的值。如果请求是一个通知类型，则此参数可以被省略。
一个标准的 JSON-RPC 2.0 请求示例如下：
{
"jsonrpc": "2.0",
"method": "subtract",
"params": [42, 23],
"id": 1
}响应对象
一个 JSON-RPC 2.0 响应数据也是一个单一的 JSON 对象，可以包含以下成员：
- jsonrpc：字符串，指定 JSON-RPC 的版本号，对于 2.0 规范来说，这个值必须是2.0。
- result：当请求成功时，包含由远程方法返回的结果。如果请求失败，则不包含此成员。
- error：当请求失败时，包含一个错误对象。如果请求成功，则不包含此成员。
- id：与请求中的 id 相同，用于识别哪个请求对应的响应。
错误对象包括以下成员：
- code：整数，用于说明错误类型。JSON-RPC 2.0 定义了一组标准的错误码。
- message：字符串，提供关于错误的简短描述。
- data：可选，可以包含额外的错误信息，比如堆栈信息等。
一个成功的响应示例如下：
{
"jsonrpc": "2.0",
"result": 19,
"id": 1
}而一个异常响应示例如下：
{
"jsonrpc": "2.0",
"error": {
"code": -32601,
"message": "Method not found"
},
"id": 1
}通知
通知是一种特殊类型的请求，没有 id 成员，因此不会得到响应。这样客户端可以向服务器发送事件或命令而无需等待回复。一个通知示例如下：
{
"jsonrpc": "2.0",
"method": "updateStatus",
"params": ["online"]
}批量请求
JSON-RPC 2.0 支持批量请求，即可以在单个请求中发送多个 JSON-RPC 调用。每个调用都是独立的 JSON-RPC 请求对象，被放在一个数组中。服务器处理这些请求后返回一个数组，其中每个元素对应于一个调用。需要注意的是，如果其中一个调用是通知，则不会有对应的响应项。
[
{
"jsonrpc": "2.0",
"method": "sum",
"params": [1, 3, 5, 7, 9],
"id": "1"
},
{
"jsonrpc": "2.0",
"method": "notify_hello",
"params": ["Alice"]
},
{
"jsonrpc": "2.0",
"method": "subtract",
"params": [42, 23],
"id": "2"
}
]错误码
JSON-RPC 2.0 规范中定义了标准的错误码，但开发者也可以根据自己的业务逻辑添加自定义的错误码。这些自定义错误代码应该在-32000到-32099之间，以避免与标准错误码冲突。通过使用自定义错误码，可以为客户端提供更加具体的错误信息。
假如这样一个场景，应用程序需要处理用户认证失败的情况，可以定义一个特定的错误码，比如 -32001，并为这个错误码配一个说明，如 Authentication failed。示例如下：
{
"jsonrpc": "2.0",
"error": {
"code": -32001,
"message": "Authentication failed"
},
"id": "1"
}此外，还可以在 error 的 data 参数中包含更多的错误细节，比如错误发生的具体位置或建议的解决方法。
JSON-RPC 2.0 定义的标准错误码如下（自定义错误吗不要使用如下几个）：
- -32700: 解析错误，服务器收到无效的 JSON。
- -32600: 无效请求，发送的 JSON 不是有效的请求对象。
- -32601: 方法未找到，方法不存在或无效。
- -32602: 无效参数，提供的参数无效。
- -32603: 内部错误，JSON-RPC 内部错误。
使用场景
JSON-RPC 2.0 的使用场景包括但不限于如下几个：
- Web 应用程序，客户端与服务器之间的异步通信，例如浏览器与后端服务交互。
- 微服务之间的通信，通过 JSON-RPC 调用其他微服务的接口。
- 物联网设备，设备与服务器之间的通信，由于 JSON-RPC 的轻量级特性，非常适合资源受限的设备。
- 移动应用，移动客户端与服务器之间的交互，减少数据传输量，提高响应速度。
- 区块链和加密货币，节点之间的通信或客户端与节点的交互，许多区块链系统（如以太坊）使用 JSON-RPC 进行接口调用。
- 远程过程调用（RPC）服务，替代传统的 SOAP 或 XML-RPC，提供简单的接口调用机制。
文档和版本控制
良好的文档对于任何 API 都至关重要，尤其是像 JSON-RPC 2.0 这样依赖于明确的请求和响应格式的协议。
- 编写清晰的 API 文档：详细描述每个方法的用途、参数、返回值和可能的错误情况。可以使用工具如 Swagger 或 Postman 来生成交互式的 API 文档。
- 保持文档更新：随着 API 的发展，确保文档始终保持最新状态，反映最新的变更和改进。
- 版本控制：为 API 引入版本控制，以便在不影响现有用户的情况下进行更新。可以在 URL 中或通过请求头指定 API 版本。
社区和支持
JSON-RPC 2.0 是一个开放的标准，拥有活跃的社区和丰富的资源。参与社区讨论、阅读官方文档和技术博客、关注相关论坛和社交媒体，都可以帮助更快地解决问题，并获取最新的最佳实践。
此外，很多流行的编程语言和框架都有现成的 JSON-RPC 库，可以大大简化开发过程。选择一个成熟且维护良好的库，不仅可以节省时间，还能减少出错的可能性。
小结
JSON-RPC 2.0作为一种轻量级的 RPC 协议，提供了如标准化的错误处理、批量请求支持和通知机制等功能，具有简单、易用、跨语言等优点，适用于多种分布式系统场景。
参考资料
- https://www.jsonrpc.org/specification