json-rpc 2.0規範
起源日期:
2010-03-26(基於2009-05-24的版本號)
修正:
2013-01-04
json-rpc 工作組
json-rpc是乙個無狀態的、輕量級的遠端過程呼叫(rpc)協議。本規範主要環繞它的處理方式定義了幾個資料結構和規則。這個概念可用於在同一程序中、套接字或http之間、或其它非常多訊息傳遞的環境中資料傳輸。它使用json (rfc 4627)作為資料格式。
json-rpc的設計非常easy!
因為json-rpc使用json格式,它擁有與json相同的型別系統(見 或 rfc 4627)。json能夠表示4種原始型別(字串、數值、布林和null)和兩種結構化型別(物件和陣列)。
術語「原始型別」在本文件中代表這四種原始json型別中的隨意一種。術語「結構化型別」代表結構化的json型別。
client和server端交換的全部成員名字都是大寫和小寫敏感的。術語函式、方法和過程都覺得是可交換的。
client被定義成原始請求物件和響應物件處理器。
server被定義成原始響應物件和請求物件處理器。
本規範的實現能夠非常easy的滿足這些要求。即使對於其它不同的client或同樣的client。
本規範沒有解決那一層次的複雜性。
json-rpc 2.0請求物件和響應物件可能與已經存在的json-rpc1.0client或server端不相容。然而。非常easy區分兩個版本號,由於2.0版本號總是包括乙個名為「jsonrpc」的成員。其值為字串「2.0」,而1.0版本號不存在。大多數2.0版本號的實現應該考慮處理1.0版本號的物件,即使不是對等的,也應該給予良好的提示。
傳送乙個請求物件到server表示乙個rpc呼叫。
請求物件包含以下這些成員:
jsonrpc
指定json-rpc版本號的字串,它必須是「2.0」。
method
呼叫的方法的名字。以rpc開頭方法名表示rpc內部的方法和擴充套件,其它地方必須不能使用。
params
它是乙個結構化的值,持有方法呼叫期間的引數值。該成員可省略。
idclient建立的乙個識別符號。假設請求中包括這個成員的話,它必須是字串、數值或null值。假設沒有包括該成員。那麼它被覺得是乙個通知。這個值一般不應該為null[1]而且假設是數值的話不應該包括小數部分[2]。
假設client包括了id成員,那麼server端必須包括相同的值在響應物件中。這個成員用於關聯請求和響應這兩個物件之間的上下文。
[1]不推薦在請求物件中使用null作為id成員的值。由於本規範使用null值作為對乙個未知id的值。
相同。由於json-rpc 1.0使用id值為null來作為通知,在處理時這可能引起混淆。
[2]小數部分可能導致總是,由於非常多小數不能被精確的表示成二進位制形式。
假設請求物件中沒有「id」成員,則表示乙個通知。通知請求物件表示client對對應的響應物件不感興趣,因此不須要返回響應物件給client。server必須不回覆乙個通知,即使是在批量請求中。
因為不會返回響應物件,所以通知不easy定義。
因此,client不會知道有不論什麼錯誤(像:「無效的引數」、「內部錯誤」等)。
rpc呼叫假設存在引數,那麼必須提供結構化的引數值。要麼通過乙個陣列的位置,要麼通過乙個物件的名字。
通過位置:引數必須是乙個陣列。包括server期望的順序的值。
通過名字:引數必須是乙個物件,物件的成員名與server期望的引數名匹配。缺少期望的引數名可能導致錯誤。
名字必須精確匹配,包含與方法期望的引數名的大寫和小寫。
當發起rpc呼叫時,server必須回覆乙個響應,通知除外。
響應被表示成乙個單一的物件。包括下列的成員:
jsonrpc
指定json-rpc版本號的字串,它必須是「2.0」。
result
當呼叫成功時,該成員是必須的。
假設呼叫方法出現錯誤時,必須不包括該成員。
該成員的值由server上呼叫的方法決定。
error
當呼叫錯誤發生時,該成員是必須的。
在呼叫期間假設沒有錯誤產生,必須不包括該成員。
該成員的值必須是乙個5.1節定義的物件。
id該成員是必須的。
它的值必須與請求物件中的id成員的值同樣。
假設檢查請求物件中的id時錯誤發生(如:轉換錯誤或無效的請求)。它必須為null。
必須包括result或error成員,可是兩個成員都必須不能同一時候包括。
當乙個rpc呼叫遇到錯誤時,響應物件必須包括乙個值為物件的error成員,該物件包括下列的成員:
code
乙個數字。表示錯誤發生的型別。
這個成員值必須是整型。
message
提供簡短錯誤描寫敘述的字串。
message應該限制為乙個簡短的句子。
data
原始型別或結構化型別值。包括了關於錯誤的附加資訊。
這個成員能夠省略。
該成員的值由server端定義(如:具體的錯誤資訊,巢狀的錯誤資訊等)。
錯誤**值-32768到-32000為保留值,作為提前定義錯誤。這個範圍內的不論什麼**。但在下表中未定義的值。保留作未來使用。這些錯誤**差點兒與下列位址中xml-rpc建議的同樣(
**訊息
含義-32700
解析錯誤
server接收到無效的json。
server解析json文字錯誤發生。
-32600
無效的請求
傳送的json不是乙個有效的請求。
-32601
方法未找到
方法不存在或不可見。
-32602
無效的引數
無效的方法引數。
-32603
內部錯誤
json-rpc內部錯誤。
-32000 to -32099
server端錯誤
保留給詳細實現定義server端錯誤。
應用程式能夠使用剩下的**來定義錯誤。
為了同一時候傳送多個請求物件,client能夠傳送乙個請求物件陣列。
在全部批量請求物件都處理完畢後,server應該使用乙個陣列作為響應,陣列中包括相應的響應物件。每乙個請求物件都應該相應乙個響應物件,像通知這樣不應該有響應物件的除外。server能夠以不論什麼寬度的並行性,以隨意的順序,併發地處理乙個批量rpc呼叫。
批量呼叫能夠使用陣列以隨意的順序返回響應物件。client可通過每乙個物件中包括的id成員在一系列請求物件和響應物件之間進行匹配。
假設批量rpc呼叫本身發生無效的json或乙個至少包括乙個值的陣列導致失敗,server生成的響應必須是乙個單一的響應物件。假設傳送到client的響應陣列中不包括響應物件,那麼server必須不能返回乙個空的陣列。而應該不返回不論什麼東西。
語法:--> 表示資料傳送到server端
<-- 表示資料傳送到client
位置引數形式的rpc呼叫:
rpc call with positional parameters:
-->
<--
-->
<--
命名引數形式的rpc呼叫:
--> , "id": 3}
<--
--> , "id": 4}
<--
通知:-->
-->
rpc呼叫乙個不存在的方法:
-->
<-- ,"id": "1"}
無效的json的rpc呼叫
rpc call with invalid json:
--> ,"id": null}
rpc call with invalid request object:
無效請求物件的rpc呼叫:
-->
<-- ,"id": null}
無效的json的rpc批量呼叫:
,, "id": null}
rpc call with an empty array:
<-- , "id": null}
無效的rpc批量呼叫(非空):
--> [1]
<-- [
,"id": null}
無效的rpc批量呼叫:
--> [1,2,3]
<-- [
,"id": null},
,"id": null},
,"id": null}
rpc批量呼叫:
--> [,,
,,, "id": "5"}, ]
<-- [,,
, "id": null},
, "id":"5"},
]rpc批量呼叫(全部呼叫都是通知):
--> [,]
<-- //批量通知呼叫什麼也不返回
以rpc開關的方法名保留作系統擴充套件。其它不論什麼地方都必須不能使用。
每乙個系統擴充套件都定義在相關的規範中。全部系統擴充套件都是可選的。
使用golang 實現JSON RPC2 0
本文同時發布於我的部落格 yeqown.github.io 遠端過程呼叫 英語 remote procedure call,縮寫為 rpc 是乙個計算機通訊協議。該協議允許執行於一台計算機的程式呼叫另一台計算機的子程式,而程式設計師無需額外地為這個互動作用程式設計。如果涉及的軟體採用物件導向程式設計...
BitTorrent 協議規範(翻譯)
元檔案和tracker的響應都採用的是一種簡單 有效 可擴充套件的格式,被稱為bencoding,它可以包含字串和整數。由於對不需要的字典關鍵字可以忽略,所以這種格式具有可擴充套件性,其它選項以後可以方便的加進來。bencoding格式如下 對於字串,首先是乙個字串的長度,然後是冒號,後面跟著實際的...
MBTiles 1 2 規範翻譯
可以參考超圖的文件mbtiles擴充套件 具體實現可以參考 利用sqlite儲存離散瓦片的思路和實現方法 mapbox提供了乙個簡單實現測試 github位址在這裡 mbtiles是在sqlite資料庫中儲存地圖瓦片資料的規範,用於即時使用和傳送.mbtiles檔案稱為tilesets 瓦片集 必須...