基本介紹
- 外文名：JSON-RPC
- 定義：遠程過程調用（RPC）傳送協定
- 數據格式： JSON（RFC 4627）
- 學科：通訊工程
約定,兼容性,請求對象,通知,參數結構,回響對象,錯誤對象,批量調用,擴展,實例比較,
約定
由於 JSON-RPC 使用JSON，它具有與其相同的類型系統。JSON可以表示四個基本類型（String、Numbers、Boolean 和 Null）和兩個結構化類型（Objects 和 Array）。任何時候文檔涉及JSON數據類型，第一個字母都必須大寫：Object、Array、String、Number、Boolean、Null。包括 True 和 False 也要大寫。
在客戶端與任何被匹配到的服務端之間交換的所有成員名字應是區分大小寫的。 函式、方法、過程都可以認為是可以互換的。客戶端被定義為請求對象的來源及回響對象的處理程式。服務端被定義為回響對象的起源和請求對象的處理程式。
該規範的一種實現為可以輕而易舉的填補這兩個角色，即使是在同一時間，同一客戶端或其他不相同的客戶端。 該規範不涉及複雜層。
兼容性
JSON-RPC 2.0 的請求對象和回響對象可能無法在較舊的 JSON-RPC 1.0 客戶端或服務端正常運行，然而我們可以很容易在兩個版本間區分出 2.0。因為 2.0 版本中必須夾帶一個命名為 jsonrpc 且值為 2.0 的欄位。而 1.0 版本是沒有此欄位的。大部分的 2.0 實現應該考慮嘗試兼容或者處理 1.0 的對象，即使不是對等的也應給其相關提示。
請求對象
傳送一個請求對象至服務端代表一個RPC調用，一個請求對象包含下列成員：
- jsonrpc
- method
- params
- id
服務端必須回答相同的值如果包含在回響對象。這個成員用來兩個對象之間的關聯上下文。在請求對象中不建議使用 NULL 作為 id 值，因為該規範將使用空值認定為未知id的請求。另外，由於JSON-RPC 1.0 的通知使用了空值，這可能引起處理上的混淆。使用小數是不確定性的，因為許多十進制小數不能精準的表達為二進制小數。
通知
沒有包含 id 成員的請求對象為通知， 作為通知的請求對象表明客戶端對相應的回響對象並不感興趣，本身也沒有回響對象需要返回給客戶端。服務端必須不回復一個通知，包含那些批量請求中的。
由於通知沒有返回的回響對象，所以通知不確定是否被定義。同樣，客戶端不會意識到任何錯誤（例如參數預設，內部錯誤）。
參數結構
RPC調用如果存在參數則必須為基本類型或結構化類型的參數值，要么為索引數組，要么為關聯數組對象。
- 索引：參數必須為數組，並包含與服務端預期順序一致的參數值。
- 關聯名稱：參數必須為對象，並包含與服務端相匹配的參數成員名稱。沒有在預期中的成員名稱可能會引起錯誤。名稱必須完全匹配，包括方法的預期參數名以及大小寫。
回響對象
當發起一個RPC調用時，除通知之外，服務端都必須回復回響。回響表示為一個 JSON 對象，使用以下欄位：
- jsonrpc
- result
- error
- id
回響對象必須包含 result 或 error 欄位，但兩個欄位不能同時存在。
錯誤對象
當一個RPC調用遇到錯誤時，返回的回響對象必須包含錯誤成員參數，並且為帶有下列成員參數的對象：
- code
- message
- data
-32768 至 -32000 為保留的預定義錯誤代碼。在該範圍內的錯誤代碼不能被開發者自己定義，保留下列以供將來使用。錯誤代碼基本與XML-RPC建議的一樣
| 錯誤碼 | 訊息 | 解釋 |
|---|---|---|
-32700 | Parse error - 語法解析錯誤 | 服務端接收到無效的 JSON。該錯誤傳送於伺服器嘗試解析 JSON 文本 |
-32600 | Invalid Request - 無效請求 | 傳送的 JSON 內容不是一個有效的請求對象。 |
-32601 | Method not found - 找不到方法 | 該方法不存在或無效。 |
-32602 | Invalid params - 無效的參數 | 無效的方法參數。 |
-32603 | Internal error - 內部錯誤 | JSON-RPC 內部錯誤。 |
-32000 to -32099 | Server error - 服務端錯誤 | 預留用於自定義的伺服器錯誤。 |
除此之外剩餘的錯誤類型代碼可供應用程式作為自定義錯誤。
批量調用
當需要同時傳送多個請求對象時，客戶端可以傳送一個包含所有請求對象的數組。
當批量調用的所有請求對象處理完成時，服務端則需要返回一個包含相對應的回響對象數組。每個回響對象都應對應每個請求對象，除非是通知的請求對象。服務端可以並發的，以任意順序和任意寬度的並行性來處理這些批量調用。
這些相應的回響對象可以任意順序的包含在返回的數組中，而客戶端應該是基於各個回響對象中的 id 成員來匹配對應的請求對象。
若批量調用的 RPC 操作本身非一個有效JSON或一個至少包含一個值的數組，則服務端返回的將單單是一個回響對象而非數組。若批量調用沒有需要返回的回響對象，則服務端不需要返回任何結果且必須不能返回一個空數組給客戶端。
擴展
以RPC開頭的方法名預留作為系統擴展，且必須不能用於其他地方。每個系統擴展都應該有相關規範文檔，所有系統擴展都應是可選的。
實例比較
用XML表示中國部分省市數據如下：
<?xmlversion="1.0"encoding="utf-8"?><country><name>中國</name><province><name>黑龍江</name><citys><city>哈爾濱</city><city>大慶</city></citys> </province><province><name>廣東</name><citys><city>廣州</city><city>深圳</city><city>珠海</city></citys> </province><province><name>台灣</name><citys> <city>台北</city> <city>高雄</city></citys> </province><province><name>新疆</name><citys><city>烏魯木齊</city></citys></province></country>
用JSON表示中國部分省市數據如下：
var country={name:"中國",provinces:[{name:"黑龍江",citys:{city:["哈爾濱","大慶"]}},{name:"廣東",citys:{city:["廣州","深圳","珠海"]}},{name:"台灣",citys:{city:["台北","高雄"]}},{name:"新疆",citys:{city:["烏魯木齊"]}}]}所以json rpc 相對 xmlrpc在頻寬、伺服器資源消耗、開發易用性方面要強很多。
