1. JSON-RPC简介2. 请求3. 响应4. 错误 4.1. 错误对象4.2. 错误码5. 批量调用6. 示例 6.1. 列表形式参数6.2. key-value形式参数6.3. 错误的调用7. 参考文献
1. JSON-RPC简介
JSON-RPC是一种基于JSON的跨语言远程调用协议。有文本传输数据小,便于调试扩展的特点。
2. 请求
JSON-RPC非常简单,在请求时向服务器传输数据格式如下(基于JSON2.0)
{ "jsonrpc" : 2.0,"method" : "sayHello", "params" : ["Hello JSON-RPC"], "id" : 1}
jsonrpc:定义JSON-RPC版本。method:调用的方法名。params:方法传入的参数,若无参数则为null。id:调用标识符。可以为字符串,不推荐包含小数(不能准确二进制化),或为null(可能引起混乱)。
3. 响应
服务器返回的数据格式也为JSON,其格式如下:
{"jsonrpc" : 2.0,"result" : "Hell JSON-RPC","error" : null,"id" : 1}
jsonrpc:定义JSON-RPC版本。result:方法返回值,调用成功时,不能为null,调用错误时,必须为null。error:调用时错误,无错误返回null,有错误时则返回一个错误对象。id:调用标识符,与调用方传入的标识一致,当请求中的id检查发生错误时(转换错误/无效请求),则必须返回null。
4. 错误
4.1. 错误对象
{"code" : 1,"message" : "Nothing found","data":null}
code:一个表示错误类型的数字。message:错误描述。data:附加信息,可为null。
4.2. 错误码
错误码-32768到-32000作为预定义错误的保留值,该范围内的任何未定义代码为未来保留使用。
5. 批量调用
客户端可以发送一个请求对象数组来进行批量调用。当所有的请求都响应完毕后,服务器应以一个数组作为响应,每个请求都应该对应一个请求对象。服务器可以以任何宽度的并行性,以任意的顺序,并发的批量处理一个RPC调用。客户端可以通过id将请求和响应进行匹配。
6. 示例
6.1. 列表形式参数
请求
{"jsonrpc":"2.0","method": "subtract","params":[42, 23],"id": 1}
响应
{"jsonrpc":"2.0","result": 19,"id": 1}
6.2. key-value形式参数
请求
{"jsonrpc":"2.0","method": "subtract","params":{"subtrahend": 23,"minuend": 42}, "id": 3}
响应
{"jsonrpc":"2.0","result": 19,"id": 3}
6.3. 错误的调用
(无id错误)
请求
{"jsonrpc":"2.0", "method": 1, "params": "bar"}
响应
{"jsonrpc": "2.0", "error":{"code": -32600, "message": "Invalid Request"},"id": null}
7. 参考文献
JSON-RPC轻量级远程调用协议介绍及使用
JSON-RPC2.0规范翻译中文版