当前位置：首页 > news >正文

JSON-RPC 2.0 规范中文版——无状态轻量级远程过程调用协议

news 来源：原创 2025/5/20 5:27:06

前言

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 2.0以其简洁、灵活的设计理念，为各种应用提供了标准的远程调用解决方案。理解并正确使用该协议，可以极大丰富你的系统交互能力，提升开发效率。

附录：常用误区和注意事项

不要在通知中使用id字段，否则会被误认为是请求。
params可以为数组或对象，根据API设计需要选择。
保持jsonrpc字段的版本一致，避免兼容性问题。
正确处理错误码和错误消息，提升调试效率。
充分利用批量操作和通知机制，优化通信效率。

这份详细的JSON-RPC 2.0规范中文版旨在帮助开发者深入理解协议本质，正确实现与使用。希望你能在实际项目中灵活应用这一标准，搭建高效、可靠的分布式系统。

版权及免责声明：本文内容参考自官方规范及公开资源，所有内容旨在教育和技术交流，非商业用途。如有侵权，请联系删除。

前言