JSON-RPC详述

翻译者:张沈鹏 zsp007@gmail.com

本文将告诉开发者们如何实现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}

...