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}

...