轻量级通信协议 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 版本。