json-rpc 2.0规范解读

JSON-RPC2.0规范由JSON-RPC工作组([email protected])维护,发布于2010-03-26(基于2009-05-24的版本), 最近的更新于2013-01-04。

整体来说,2.0版本的JSON-RPC规范改动的很小,大的改动大概有3点:

  1. 参数可以用数组或命名参数
  2. 批量请求的细节明确化了
  3. 错误处理的机制标准化了

与1.0版本的兼容性

  • 建议2.0规范的实现兼容1.0协议,但是不强制要求,如果不能兼容,建议给出友好提示。
  • 请求和响应报文加了个参数表示协议的版本号:jsonrpc,它必须是“2.0”。
  • method的修改:以rpc开头方法名表示rpc内部的方法和扩展,其他地方必须不能使用。
  • 请求参数可以使用数组[参数1,参数2,,,],也可以使用命名参数{key:value}
  • 请求参数为空时params可省略。
  • id一般不应该为null,是数值的话不应该是小数。
  • 请求里没有id时,被当做通知。(1.0时这里是id为null。)
  • 请求参数必须精确匹配,包括大小写。
  • 应答必须包含result或error,但是两个成员都必须不能同时包含。

批量请求

终于说清楚了这个批量请求怎么操作,就是一次请求里用数组包装多个请求对象。示例如下,打包5个请求:

--> [
        {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
        {"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
        {"foo": "boo"},
        {"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"},
        {"jsonrpc": "2.0", "method": "get_data", "id": "9"} 
    ]
<-- [
        {"jsonrpc": "2.0", "result": 7, "id": "1"},
        {"jsonrpc": "2.0", "result": 19, "id": "2"},
        {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
        {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "5"},
        {"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
    ]

规范定义了所有的请求应该并发执行,并且返回不保证顺序,客户端自己使用id去匹配对应的请求和响应。而且对于请求的处理中只要有一个出错,则返回一个统一的错误信息(就是不区分哪一条失败,全部都算失败了)。 这个设计看起来是针对事务考虑的,但是在一般的使用场景里应该会比较麻烦。

错误对象

改进的error机制是,error变成了一个明确定义的对象。包括三个属性:

  • code:数值,见下一节错误代码。
  • message:字符串格式的错误信息。
  • data:可选的,服务器端定义的一个数值或是对象,来附加额外的信息。

比原来的粗放型错误机制好多了。

错误代码

从XML-RPC借来了服务器端的错误代码:

code message meaning
-32700 Parse error Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
-32600 Invalid Request The JSON sent is not a valid Request object.
-32601 Method not found The method does not exist / is not available.
-32602 Invalid params Invalid method parameter(s).
-32603 Internal error Internal JSON-RPC error.
-32000 to -32099 Server error Reserved for implementation-defined server-errors.

参考资料

郑重声明:本站内容如果来自互联网及其他传播媒体,其版权均属原媒体及文章作者所有。转载目的在于传递更多信息及用于网络分享,并不代表本站赞同其观点和对其真实性负责,也不构成任何其他建议。