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