JSON-RPC

JSON-RPC，是一个無狀態而且輕量級的遠端程序呼叫（RPC）傳送協定，其傳送的內容透過 JSON 為主。佮一般的比較起來 REST 透過網址（如 ` GET / user `）呼叫遠端侍服器，JSON-RPC 直接佇咧內容中定義矣欲呼叫的函式名稱（如 ` { " method " : " getUser " } `）， 這也令開發者袂陷入這是使用 PUT 抑是講 PATCH 的問題內底。本規範主要定義一寡資料結構佮其實相關的處理規則。伊允准執行佇咧基於 Socket、HTTP 等真濟無仝款訊息傳輸環境的仝一行程中。其使用 JSON（RFC 四千六百二十七）做資料的格式。

約定

因為 JSON-RPC 使用 JSON，伊有佮其他的別款的系統。JSON 會當表示四个基本的類型（String、Numbers、Boolean 和 Null）佮兩个結構化類型（Objects 和 Array）。 任何時陣文件牽涉著 JSON 資料類型，第一字母攏著愛大寫：Object、Array、String、Number、Boolean、Null。包括講 True 和 False 嘛愛大寫。

佇客戶捀佮任何被匹配著的侍服器捀之間交換的所有成員的名應該是區分大細寫的。函式、方法、過程攏會當認為是會當相換的。客戶捀予人定義為請求物件的來源佮回應物件的處理程式。侍服器捀被定義為著回應物件的起源佮請求物件的處理程式。

該規範的一種實現為會當簡單來填補這兩個角色，就算講是仝一个時陣，仝一客戶捀抑是仝款無相仝的客戶捀。該規範無牽涉著複雜層。

相容性

JSON-RPC 強欲消息的請求物件佮回應物件可能是無法度佇較舊的 JSON-RPC 一鋪零客戶捀抑是侍服器捀正常執行，毋過咱會當真容易佇兩个版本間區分出二石樵。因為二鋪空版本內底著愛挾一个號名 jsonrpc 而且值為二允空的欄位。一簇零版本是無遮爾欄位的。大部份二四界的空實現應該考慮試看覓相容抑是處理一鼻空的物件，就算毋是對等的嘛應予其相關提示。

請求物件

傳送一个請求物件就愛等服器捀代表一个 RPC 搧叫，一个請求物件包括下列做員：

• jsonrpc
• method
• params
• id

侍服器捀著愛回答相仝的值若包含佇咧回應物件。這个成員用來兩个物件之間的關聯頂下文。佇咧請求物件無建議用 NULL 做為 id 值，因為這个規範共使用空值認定做無知影 id 的請求。另外咧，因為 JSON-RPC 一鋪零的通知使用空值，這可能引起處理的透濫。使用小數是無確定性的，因為真濟十進位小數袂當精準的表達為二進位小數。

通知

無包括 id 成員的請求物件為通知，作為通知的請求物件表明客戶捀對相應的回應物件閣無感興趣，本身嘛無回應物件需要閣轉去予客戶捀。侍服器捀著愛無回覆一个通知，包含講遐的批次請求中的。

因為通知無轉去的回應物件，所以通知無確定敢是予人定義。仝款，客戶捀袂意識著任何錯誤（譬如講參數預設，內部錯誤）。

參數結構

RPC 呼叫若存在參數則必須為基本類型抑是結構化類型的參數值，欲按怎替陣索引，欲按怎為關聯陣列的物件。

• 索引：參數必須替陣列，並且包含侍服器捀預期順序一致的參數值。
• 關聯名稱：參數必須替物件，並且包括侍服器捀相匹配的參數成員名稱。無佇咧期中的成員名稱可能會引起錯誤。名稱著愛完全匹配，包括方法的預期參數名佮大細寫。

回應東西

有發起一个 RPC 搧叫時，除通知以外，侍服器捀攏著愛回覆。回應表示講為一个 JSON 東西，使用以下欄位：

• jsonrpc
• result
• error
• id

回應物件著愛包含 result 抑是 error 欄位，毋過兩个欄位袂當仝个時陣存在。

錯誤物件

做一个 RPC 呼叫拄著錯誤的時，倒轉來的回應物件著愛包含錯誤成員參數，並且替帶有下列成員參數的物件：

• code
• message
• data

被三鋪二千七百六十八到抹三方二千為著欲保留預定義錯誤代碼。佇咧這个範圍內底的錯誤代碼袂使去予開發者家己的定義，保留下列以供將來使用。錯誤代碼基本佮 XML-RPC 建議的仝款除了這以外賰的錯誤類型代碼會當供應用程式來做自訂的錯誤。

批相對叫

當需要同時傳送幾个請求物件的時陣，客戶捀會當傳送一个包含所有的請求物件的陣列。

當批次呼的所有請求物件處理完成的時陣，侍服器捀著愛倒轉來一个包含相對應的回應物件陣列。逐个回應物件攏應對應逐个請求物件，除非是通知的請求物件。侍服器捀會使並且做的，任意順序佮任意闊度的並列性來處理遮的批次呼叫。

遮的相應的回應的物件會當任意順序的包含佇返回的陣列內底，毋過客戶捀應該是每一个回應的物件中的 id 成員來匹配對應的去請求物件。

若是批評叫的 RPC 操作本身非一个有效 JSON 抑是一个至少包含一个值的陣列，則侍服器轉來單是一个回應的物件毋是陣列。若是批次呼叫無需要倒轉來的回應物件，則侍服器捀無需要倒轉去任何結果著愛倒轉來一个空陣列予客戶捀。

範例

佇以下的例內底，`--> ` 表示資料傳送到侍服器，` <--` 表示資料傳送到使用者捀。

𤆬索引陣列參數的 rpc 搧叫：

𤆬關聯陣列參數的 RPC 搧叫：

通知：

無包括講叫方法的 RPC 搧叫：

包括無效 JSON 的 RPC 搧叫：

包含無效請求物件的 RPC 搧叫：

包括無效 JSON 的 RPC 批相對叫：

包含講空陣列的 RPC 搧叫：

非空而且無效 RPC 批相對叫：

無效的 RPC 批相對叫：

RPC 批相對叫：

所有攏為著通知的 RPC 批相對叫：

擴充

以 RPC 頭的方法名預留做系統擴充，而且你著愛袂使用其他的所在。逐个系統擴充攏應該有相關規範文件，所有系統擴充攏應當選的。

外部連結

• JSON-RPC 二鋪零規範 ( 中文版 )
• jsonrpc . org / specification