JSON-RPC 2.0 规范中文版——无状态轻量级远程过程调用协议
前言
JSON-RPC是一种简单、轻量且无状态的远程过程调用（RPC）协议，它允许不同系统通过标准化的数据格式进行通信。自2010年由JSON-RPC工作组发布以来，已成为众多应用中实现远程交互的基础协议之一。本规范主要表达了JSON-RPC 2.0版本的核心内容和处理规则，以保证各实现之间的兼容性和基础一致性。
本文由翻译者整理并编辑，旨在帮助中文读者理解和掌握JSON-RPC 2.0的技术细节与使用规范。
一、概述
JSON-RPC是建立在JSON（JavaScript Object Notation）之上的一种协议（符合RFC 4627），它定义了一套数据结构和交互规则，支持多种传输协议（如HTTP、WebSocket、TCP socket等）。其特点如下：
- 无状态（Stateless）：每个请求都独立，无依赖历史状态。
- 轻量级（Lightweight）：没有繁琐的通信机制，只有必要的数据结构。
- 跨平台：可以运行在任意支持JSON的环境中。
- 多角色支持：既可以是客户端，也可以是服务端，也可以在同一应用内部既充当请求者又承担服务角色。
二、约定与用语
本规范中涉及的关键词在RFC 2119中定义，表示其强制性或推荐性。例如：
- MUST：必须
- SHALL：强制要求
- SHOULD：建议
- MAY：可选
JSON类型
- Primitive（基本类型）：String、Number、Boolean、Null
- Structured（结构化类型）：Object（对象）、Array（数组）
在文档中，标记为“Object”、“Array”、“String”、“Number”、“Boolean”、“Null”的类型名，首字母必须大写。
名称区分大小写
所有成员名（字段名）必须区分大小写。
角色定义
- 客户端（Client）：请求发起方，发起请求，并处理响应。
- 服务端（Server）：请求应答方，接受请求并发出响应。
三、版本兼容性
JSON-RPC 2.0定义了请求和响应的结构，若要与旧版本（1.0）兼容：
- 2.0请求对象必须包含
"jsonrpc": "2.0"字段。 - 1.0版本不包含该字段。
- 实现应尝试处理1.0格式请求，但优先处理2.0格式。
四、请求对象（Request Object）
客户端发起远程调用时，使用请求对象进行描述。请求对象具有以下成员：
| 成员名 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
jsonrpc | String | 协议版本，必须为字符串"2.0" | 必须 |
method | String | 方法名，代表要调用的远程方法名（内部方法用开头“rpc.”做前缀） | 必须 |
params | Array或Object（可选） | 调用参数，可以是数组（索引参数）或对象（命名参数） | 可选 |
id | String、Number或Null | 客户端唯一标识符，用于匹配请求与响应，通知请求没有此字段或用Null | 可选（通知没有） |
请求通知（Notification）
如果请求对象没有"id"字段，则为通知。通知代表客户端不需要响应结果，服务端无须返回响应。
示例
// 正常请求 { "jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1 }
// 通知 { "jsonrpc": "2.0", "method": "update", "params": [1, 2, 3] }
五、响应对象（Response Object）
服务端对请求的回应，以响应对象形式出现。响应对象有以下成员：
| 成员名 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
jsonrpc | String | 协议版本，必须为字符串"2.0" | 必须 |
result | 任意类型（成功时存在） | 调用成功后的返回值 | 可选 |
error | Error对象（失败时存在） | 出现错误时的错误信息，不能与result同时出现 | 可选 |
id | String、Number或Null | 请求中的id，用于匹配请求（通知没有此字段或用Null） | 必须 |
成功响应
{ "jsonrpc": "2.0", "result": 19, "id": 1 }
失败响应（错误对象）
{ "jsonrpc": "2.0", "error": { "code": -32601, "message": "Method not found" }, "id": 1 }
ID对应关系说明
- 若请求中
id是字符串或数字，响应中应保持一致，确保客户端可以正确匹配。 - 通知请求不应有响应。
六、错误对象（Error Object）
错误信息定义如下：
| 成员名 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
code | Integer | 错误类型代码，用于区分错误类别 | 必须 |
message | String | 简要描述错误信息 | 必须 |
data | 任意类型 | 可选，附加错误信息（嵌套结构、详细信息等） | 可选 |
预定义错误码
| 码值 | 描述 | 说明 |
|---|---|---|
| -32700 | Parse error（解析错误） | JSON格式不正确，解析失败 |
| -32600 | Invalid Request（无效请求） | 请求结构无效或格式错误 |
| -32601 | Method not found（方法不存在） | 调用的方法未定义 |
| -32602 | Invalid params（参数无效） | 参数不符合预期 |
| -32603 | Internal error（内部错误） | 服务器内部错误 |
| -32000至-32099 | Server error（服务器错误） | 预留用于定义自定义错误码 |
七、批量请求（Batch）
批量请求允许一次发起多个请求或通知，服务端将会逐个处理，并返回包含所有响应的数组。
特点
- 请求体为数组，每个元素都是请求或通知对象。
- 只要有一个请求无效，返回的响应数组中会对应错误。
- 通知（无id请求）没有响应。
- 可以混合请求和通知。
举例
[ { "jsonrpc": "2.0", "method": "sum", "params": [1, 2, 3], "id": "1" }, { "jsonrpc": "2.0", "method": "notify_hello", "params": [7] }, { "jsonrpc": "2.0", "method": "subtract", "params": [10, 5], "id": "2" } ]
对应的响应：
[ { "jsonrpc": "2.0", "result": 6, "id": "1" }, // 通知无响应 { "jsonrpc": "2.0", "result": 5, "id": "2" } ]
特别留意：
- 若请求数组为空或无效，服务端应返回错误响应（非数组）。
- 批量中所有通知都没有响应（集合为空），也不返回任何内容。
八、示例：常用调用场景
- 正常调用：
{"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
- 通知调用：
{"jsonrpc": "2.0", "method": "update", "params": [1, 2, 3]}
- 错误示例：
请求中包含无效JSON或缺失必要字段，解析失败：
{"jsonrpc": "2.0", "method": "unknown_method", "params": {}, "id": 10}
服务端响应：
{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": 10}
九、扩展机制
以rpc开头的方法名保留给系统扩展，不应在正常业务调用中使用。所有扩展都应有对应的文档说明，且实现为可选。
十、版权声明
本协议由JSON-RPC工作组首次发布，任何人可自由使用、复用、修改，须包含版权声明并遵守共享协议。
结语
JSON-RPC 2.0以其简洁、灵活的设计理念，为各种应用提供了标准的远程调用解决方案。理解并正确使用该协议，可以极大丰富你的系统交互能力，提升开发效率。
附录：常用误区和注意事项
- 不要在通知中使用
id字段，否则会被误认为是请求。 params可以为数组或对象，根据API设计需要选择。- 保持
jsonrpc字段的版本一致，避免兼容性问题。 - 正确处理错误码和错误消息，提升调试效率。
- 充分利用批量操作和通知机制，优化通信效率。
这份详细的JSON-RPC 2.0规范中文版旨在帮助开发者深入理解协议本质，正确实现与使用。希望你能在实际项目中灵活应用这一标准，搭建高效、可靠的分布式系统。
版权及免责声明：本文内容参考自官方规范及公开资源，所有内容旨在教育和技术交流，非商业用途。如有侵权，请联系删除。