JSON-RPC 2.0 规范(中文版)

JSON-RPC 2.0 规范(中文版)。 JSON-RPC是一个无状态且轻量级的远程过程调用(RPC)协议。 本规范主要定义了一些数据结构及其相关的处理规则。它允许运行在基于socket,http等诸多不同消息传输环境的同一进程中。其使用JSON（RFC 4627）作为数据格式。 ### JSON-RPC 2.0 规范解析 #### 概述 JSON-RPC 2.0 是一种无状态、轻量级的远程过程调用（RPC）协议，旨在简化跨网络的应用通信流程。该规范定义了一系列数据结构及处理规则，以支持不同消息传输环境（如基于 socket 或 HTTP 的环境）下的进程间通信。JSON-RPC 2.0 使用 JSON（RFC 4627）作为数据格式，使得其能够高效地在多种平台上进行部署。 #### 约定 - **术语标准化**：文档中使用的大写字母规定了 JSON 数据类型的标准写法，例如 Object、Array、String、Number、Boolean 和 Null。此外，True 和 False 这样的布尔值也被规定为大写形式。 - **关键字含义**：文档使用了 RFC 2119 中规定的术语，如 MUST、SHALL NOT、SHOULD 等，以明确规范中的强制性和推荐性条款。 - **大小写敏感性**：所有成员名字在客户端和服务端之间的交互过程中都是大小写敏感的。 - **角色定义**：文档明确了客户端和服务端的角色定义。客户端负责发送请求并处理响应；服务端接收请求并生成响应。 #### 兼容性 - **版本区分**：JSON-RPC 2.0 与 JSON-RPC 1.0 不完全兼容。2.0 版本通过在每个请求和响应中加入 "jsonrpc" 字段（值为 "2.0"）来区分自身。 - **向后兼容性**：虽然 2.0 版本不完全兼容于 1.0 版本，但建议大多数 2.0 实现考虑到向后兼容的问题，尽可能处理 1.0 版本的请求，并在遇到不兼容情况时给出提示。 #### 请求对象 - **基本结构**：请求对象必须包含 "jsonrpc" 字段，其值为 "2.0"，指示使用的是 JSON-RPC 2.0 协议。 - **方法调用**："method" 字段用于指定要调用的方法名。方法名采用字符串形式，其中以 "rpc." 开头的方法名保留用于 RPC 内部方法或扩展。 - **参数传递**："params" 字段可选，用于传递方法所需的参数。这些参数可以是基本类型（如字符串、数字、布尔值等），也可以是结构化类型（如对象或数组）。 - **唯一标识**："id" 字段用于唯一标识客户端发出的请求。此字段的值可以是字符串、数字或 null。如果缺少 "id" 字段，则被视为通知，服务端不需要做出响应。 - **通知**：没有 "id" 字段的请求被视为通知，即服务端不需要返回响应。通知主要用于异步消息发送。 - **参数结构**：当方法需要参数时，这些参数可以采用索引数组或关联数组的形式。索引数组按照参数顺序排列，关联数组则使用键值对形式。 #### 响应对象 - **响应结构**：响应对象必须包含 "jsonrpc" 字段，其值为 "2.0"，表明遵循 JSON-RPC 2.0 协议。 - **结果返回**：如果请求成功，响应对象通常包含 "result" 字段，用于返回方法执行的结果。 - **错误处理**：如果请求失败或发生错误，响应对象会包含 "error" 字段，用于描述错误信息。 - **ID 对应**：响应对象中的 "id" 字段应与请求对象中的 "id" 字段相同，以便客户端识别响应对应的请求。 #### 批量调用 JSON-RPC 2.0 支持批量调用，即在一个请求中包含多个请求对象。服务端需对每个请求分别处理，并返回包含相应响应的数组。 #### 示例与扩展 文档中提供了详细的示例以帮助理解和实施 JSON-RPC 2.0 协议。此外，还介绍了如何进行协议的扩展以适应特定需求。 JSON-RPC 2.0 规范通过简洁的数据结构和明确的操作流程，为开发人员提供了一个易于理解且灵活的远程过程调用解决方案。无论是对于新手还是有经验的开发者来说，该规范都能够有效地促进不同应用间的交互与集成。