JSON-RPC遠程調用協議

• 1. JSON-RPC簡介
• 2. 請求
• 3. 響應
• 4. 錯誤
  • 4.1. 錯誤對象
  • 4.2. 錯誤碼
• 5. 批量調用
• 6. 示例
  • 6.1. 列表形式參數
  • 6.2. key-value形式參數
  • 6.3. 錯誤的調用
• 7. 參考文獻

1. JSON-RPC簡介

JSON-RPC是一種基於JSON的跨語言遠程調用協議。有文本傳輸數據小，便於調試擴展的特色。

2. 請求

JSON-RPC很是簡單，在請求時向服務器傳輸數據格式以下(基於JSON2.0)

{ 
    "jsonrpc" : 2.0,
    "method" : "sayHello", 
    "params" : ["Hello JSON-RPC"], 
    "id" : 1
}

• jsonrpc:定義JSON-RPC版本。
• method:調用的方法名。
• params:方法傳入的參數，若無參數則爲null。
• id:調用標識符。能夠爲字符串，不推薦包含小數（不能準確二進制化），或爲null（可能引發混亂）。

3. 響應

服務器返回的數據格式也爲JSON，其格式以下：

{
    "jsonrpc" : 2.0,
    "result" : "Hell JSON-RPC",
    "error" : null,
    "id" : 1
}

• jsonrpc:定義JSON-RPC版本。
• result:方法返回值，調用成功時，不能爲null，調用錯誤時，必須爲null。
• error:調用時錯誤，無錯誤返回null，有錯誤時則返回一個錯誤對象。
• id:調用標識符，與調用方傳入的標識一致，當請求中的id檢查發生錯誤時（轉換錯誤/無效請求），則必須返回null。

4. 錯誤

4.1. 錯誤對象

{
    "code" : 1,
    "message" : "Nothing found",
    "data":null
}

• code：一個表示錯誤類型的數字。
• message：錯誤描述。
• data：附加信息，可爲null。

4.2. 錯誤碼

錯誤碼-32768到-32000做爲預約義錯誤的保留值，該範圍內的任何未定義代碼爲將來保留使用。

代碼	錯誤	含義
-32700	解析錯誤	服務器接收到無效的JSON；服務器解析JSON文本發生錯誤。
-32600	無效的請求	發送的JSON不是一個有效的請求。
-32601	方法未找到	方法不存在或不可見。
-36602	無效的參數	無效的方法參數。
-36603	內部錯誤	JSON-RPC內部錯誤。
-32000到-32099	服務器端錯誤	保留給具體實現服務器端錯誤。

5. 批量調用

客戶端能夠發送一個請求對象數組來進行批量調用。當全部的請求都響應完畢後，服務器應以一個數組做爲響應，每一個請求都應該對應一個請求對象。服務器能夠以任何寬度的並行性，以任意的順序，併發的批量處理一個RPC調用。客戶端能夠經過id將請求和響應進行匹配。

6. 示例

6.1. 列表形式參數

請求

{
    "jsonrpc":"2.0",
    "method": "subtract",
    "params":[42, 23],
    "id": 1
}

響應

{
    "jsonrpc":"2.0",
    "result": 19,
    "id": 1
}

6.2. key-value形式參數

請求

{
    "jsonrpc":"2.0",
    "method": "subtract",
    "params":{
                "subtrahend": 23,
                "minuend": 42
             }, 
    "id": 3
}

響應

{
    "jsonrpc":"2.0",
    "result": 19,
    "id": 3
}

6.3. 錯誤的調用

（無id錯誤）
請求

{
    "jsonrpc":"2.0", 
    "method": 1, 
    "params": "bar"
}

響應

{
    "jsonrpc": "2.0", 
    "error":{
                "code": -32600, 
                "message": "Invalid Request"
            },
    "id": null
}

7. 參考文獻

JSON-RPC輕量級遠程調用協議介紹及使用

JSON-RPC2.0規範翻譯中文版