fguillot json rpc_JSON-RPC远程调用协议

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作为预定义错误的保留值，该范围内的任何未定义代码为未来保留使用。

代码

错误

含义

-32700

解析错误

服务器接收到无效的JSON；服务器解析JSON文本发生错误。

-32600

无效的请求

发送的JSON不是一个有效的请求。

-32601

方法未找到

方法不存在或不可见。

-36602

无效的参数

无效的方法参数。

-36603

内部错误

JSON-RPC内部错误。

-32000到-32099

服务器端错误

保留给具体实现服务器端错误。

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. 参考文献