JSON-RPC詳述

翻譯者:張沈鵬 zsp007@gmail.com

本文將告訴開發(fā)者們?nèi)绾螌?shí)現(xiàn)JSON協(xié)議.

(現(xiàn)在正在審批JSON-RPC 1.1草案. )

= 概覽 =

JSON-RPC是一個(gè)輕量級的遠(yuǎn)程調(diào)用協(xié)議.它的設(shè)計(jì)理念是:簡單!

數(shù)據(jù)通訊由兩部分組成.在一次連接的生命期內(nèi),一端將發(fā)出一個(gè)請求來調(diào)用另一端的函數(shù).另一端將回應(yīng)該請求,除非這個(gè)請求是一個(gè)公告.

== 請求(函數(shù)調(diào)用) ==

通過向一個(gè)遠(yuǎn)程服務(wù)器發(fā)送一個(gè)請求來調(diào)用一個(gè)遠(yuǎn)程函數(shù).該請求是一個(gè)用JSON進(jìn)行了編碼(序列化)的對象.

它有3個(gè)部分:
 * 函數(shù)名
 * 參數(shù)數(shù)組
 * 標(biāo)識碼 - 請求的標(biāo)識碼是用來匹配它所對應(yīng)的回復(fù).

== 回復(fù) ==

當(dāng)調(diào)用請求結(jié)束時(shí),服務(wù)器將回復(fù)該請求.回復(fù)同樣是用JSON進(jìn)行了編碼的對象.

它有3個(gè)部分:

 * 返回值 - 如果發(fā)生調(diào)用錯(cuò)誤它的值可能為空 
 * 錯(cuò)誤信息 - 如果沒錯(cuò)誤,它為空
 * 標(biāo)識碼 - 和請求的標(biāo)識碼一致
 
== 公告 ==

公告是一種沒有回復(fù)的請求.同樣為用JSON編碼對象.

它的標(biāo)識碼為空,其他和普通請求一致. 

= JSON-RPC 與傳輸方式無關(guān)的協(xié)議 =
本協(xié)議不限制你的使用的傳輸協(xié)議,不過推薦使用TCP/IP端口流(socket streams).被編碼了的請求和回復(fù)通過這種字節(jié)流傳輸.

請求和回復(fù)隨時(shí)可以發(fā)送給另一端.公告無需回復(fù),僅當(dāng)有請求時(shí)才發(fā)送回復(fù).

結(jié)束連接回導(dǎo)致未答復(fù)的端的異常.無效的請求和回復(fù)講關(guān)閉連接.

== HTTP中的JSON-RPC ==
進(jìn)行一些限制,便可以通過HTTP請求來進(jìn)行通訊.

Http客戶端和Http服務(wù)器端間可能有多個(gè)Http請求.一個(gè)客戶端可以通過一次包含多個(gè)JSON對象的HTTP POST進(jìn)行多個(gè)請求,公告,回復(fù).

服務(wù)器端必須回復(fù)所有的請求,同時(shí)可能發(fā)出新的請求或通知.客戶端也要再一次通過HTTP POST響應(yīng). 

為了和服務(wù)器端再一次建立連接,客戶端可能需要主動發(fā)送一次空的HTTP POST.

無效的請求會導(dǎo)致連接的關(guān)閉.無效的回復(fù)所有沒回復(fù)的客戶端的異常.關(guān)閉連接會導(dǎo)致所有沒回復(fù)的客戶端的異常.

= JSON Class演示 =

JSON中只定義了簡單的數(shù)據(jù)類型.為了彌補(bǔ)這些不足,JSON引進(jìn)了對象的屬性的定義.

{"__jsonclass__":["constructor", [param1,...]], "prop1": 
...}

這個(gè)對象通過constructor的參數(shù)數(shù)組初始化,當(dāng)初始化完成后,會應(yīng)用它的屬性(prop1, ...). 

= 通訊演示 =

--> 表示發(fā)送給服務(wù)器端的信息
<-- 服務(wù)器端的回應(yīng)

service.echo("Hello JSON-RPC") 
--> { "method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
<-- { "result": "Hello JSON-RPC", "error": null, "id": 1}

多重請求/回應(yīng)

本例展示了一次通訊的部分內(nèi)容,聊天的服務(wù)器發(fā)送給每個(gè)客戶端一個(gè)公告.客戶端通過請求向服務(wù)器端發(fā)送消息,通過服務(wù)器回復(fù)表示消息是否送到.
...

--> {"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}

...