JSON RPC 2 0規範 翻譯 中文版

2022-08-17 16:39:20 字數 4509 閱讀 6651

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 瓦片集 必須...