JSON-RPC详述
翻译者:张沈鹏 [email protected]
本文将告诉开发者们如何实现JSON协议.
(现在正在审批JSON-RPC 1.1草案. )
= 概览 =
JSON-RPC是一个轻量级的远程调用协议.它的设计理念是:简单!
数据通讯由两部分组成.在一次连接的生命期内,一端将发出一个请求来调用另一端的函数.另一端将回应该请求,除非这个请求是一个公告.
== 请求(函数调用) ==
通过向一个远程服务器发送一个请求来调用一个远程函数.该请求是一个用JSON进行了编码(序列化)的对象.
它有3个部分:
* 函数名
* 参数数组
* 标识码 - 请求的标识码是用来匹配它所对应的回复.
== 回复 ==
当调用请求结束时,服务器将回复该请求.回复同样是用JSON进行了编码的对象.
它有3个部分:
* 返回值 - 如果发生调用错误它的值可能为空
* 错误信息 - 如果没错误,它为空
* 标识码 - 和请求的标识码一致
== 公告 ==
公告是一种没有回复的请求.同样为用JSON编码对象.
它的标识码为空,其他和普通请求一致.
= JSON-RPC 与传输方式无关的协议 =
本协议不限制你的使用的传输协议,不过推荐使用TCP/IP端口流(socket streams).被编码了的请求和回复通过这种字节流传输.
请求和回复随时可以发送给另一端.公告无需回复,仅当有请求时才发送回复.
结束连接回导致未答复的端的异常.无效的请求和回复讲关闭连接.
== HTTP中的JSON-RPC ==
进行一些限制,便可以通过HTTP请求来进行通讯.
Http客户端和Http服务器端间可能有多个Http请求.一个客户端可以通过一次包含多个JSON对象的HTTP POST进行多个请求,公告,回复.
服务器端必须回复所有的请求,同时可能发出新的请求或通知.客户端也要再一次通过HTTP POST响应.
为了和服务器端再一次建立连接,客户端可能需要主动发送一次空的HTTP POST.
无效的请求会导致连接的关闭.无效的回复所有没回复的客户端的异常.关闭连接会导致所有没回复的客户端的异常.
= JSON Class演示 =
JSON中只定义了简单的数据类型.为了弥补这些不足,JSON引进了对象的属性的定义.
{"__jsonclass__":["constructor", [param1,...]], "prop1":
...}
这个对象通过constructor的参数数组初始化,当初始化完成后,会应用它的属性(prop1, ...).
= 通讯演示 =
--> 表示发送给服务器端的信息
<-- 服务器端的回应
service.echo("Hello JSON-RPC")
--> { "method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
<-- { "result": "Hello JSON-RPC", "error": null, "id": 1}
多重请求/回应
本例展示了一次通讯的部分内容,聊天的服务器发送给每个客户端一个公告.客户端通过请求向服务器端发送消息,通过服务器回复表示消息是否送到.
...
--> {"method": "postMessage", "params": ["Hello all!"], "id": 99}
<-- {"result": 1, "error": null, "id": 99}
<-- {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
<-- {"method": "handleMessage", "params": ["user3", "sorry, gotta go now, ttyl"], "id": null}
--> {"method": "postMessage", "params": ["I have a question:"], "id": 101}
<-- {"method": "userLeft", "params": ["user3"], "id": null}
<-- {"result": 1, "error": null, "id": 101}
...