json-rpc 2.0規範解讀

標籤：json   rpc   

JSON-RPC2.0規範由JSON-RPC工作群組（[email protected]）維護，發佈於2010-03-26(基於2009-05-24的版本)， 最近的更新於2013-01-04。

整體來說，2.0版本的JSON-RPC規範改動的很小，大的改動大概有3點：

1. 參數可以用數組或具名引數
2. 批量請求的細節明確化了
3. 錯誤處理的機制標準化了

與1.0版本的相容性

• 建議2.0規範的實現相容1.0協議，但是不強制要求，如果不能相容，建議給出友好提示。
• 請求和響應報文加了個參數表示協議的版本號碼：jsonrpc，它必須是“2.0”。
• method的修改：以rpc開頭方法名表示rpc內部的方法和擴充，其他地方必須不能使用。
• 請求參數可以使用數組[參數1，參數2，，，]，也可以使用具名引數{key:value}。
• 請求參數為空白時params可省略。
• id一般不應該為null，是數值的話不應該是小數。
• 請求裡沒有id時，被當做通知。（1.0時這裡是id為null。）
• 請求參數必須精確匹配，包括大小寫。
• 應答必須包含result或error，但是兩個成員都必須不能同時包含。

批量請求

終於說清楚了這個批量請求怎麼操作，就是一次請求裡用數組封裝多個請求對象。樣本如下，打包5個請求：

--> [        {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},        {"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},        {"foo": "boo"},        {"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"},        {"jsonrpc": "2.0", "method": "get_data", "id": "9"}     ]<-- [        {"jsonrpc": "2.0", "result": 7, "id": "1"},        {"jsonrpc": "2.0", "result": 19, "id": "2"},        {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},        {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "5"},        {"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}    ]

規範定義了所有的請求應該並發執行，並且返回不保證順序，用戶端自己使用id去匹配對應的請求和響應。而且對於請求的處理中只要有一個出錯，則返回一個統一的錯誤資訊（就是不區分哪一條失敗，全部都算失敗了）。 這個設計看起來是針對事務考慮的，但是在一般的使用情境裡應該會比較麻煩。

錯誤對象

改進的error機制是，error變成了一個明確定義的對象。包括三個屬性：

• code：數值，見下一節錯誤碼。
• message：字串格式的錯誤資訊。
• data：可選的，伺服器端定義的一個數值或是對象，來附加額外的資訊。

比原來的粗放型錯誤機制好多了。

錯誤碼

從XML-RPC借來了伺服器端的錯誤碼：

code	message	meaning
-32700	Parse error Invalid	JSON was received by the server. An error occurred on the server while parsing the JSON text.
-32600	Invalid Request	The JSON sent is not a valid Request object.
-32601	Method not found	The method does not exist / is not available.
-32602	Invalid params	Invalid method parameter(s).
-32603	Internal error	Internal JSON-RPC error.
-32000 to -32099	Server error	Reserved for implementation-defined server-errors.

參考資料

• 2.0規範全文
• 2.0對1.0的改進

json-rpc 2.0規範解讀