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}
...