(譯) JSON-RPC 2.0 規範(中文版)

leozvc發表於2015-01-30
JSONRPC

本文部落格wiki地址:http://wiki.geekdream.com/Specification/json-rpc_2.0.html

1.概述

JSON-RPC是一個無狀態且輕量級的遠端過程呼叫(RPC)協議。 本規範主要定義了一些資料結構及其相關的處理規則。它允許執行在基於socket,http等諸多不同訊息傳輸環境的同一程式中。其使用JSON（RFC 4627）作為資料格式。

它為簡單而生!

2.約定

文件中關鍵字”MUST”、”MUST NOT”、”REQUIRED”、”SHALL”、”SHALL NOT”、”SHOULD”、”SHOULD NOT”、”RECOMMENDED”、”MAY”和 “OPTIONAL” 將在RFC 2119 中得到詳細的解釋及描述。

由於JSON-RPC使用JSON，它具有與其相同的型別系統(見http://www.json.org或RFC 4627)。JSON可以表示四個基本型別(String、Numbers、Booleans和Null)和兩個結構化型別(Objects和Arrays)。 規範中，術語“Primitive”標記那4種原始型別，“Structured”標記兩種結構化型別。任何時候文件涉及JSON資料型別，第一個字母都必須大寫：Object，Array，String，Number，Boolean，Null。包括True和False也要大寫。

在客戶端與任何被匹配到的服務端之間交換的所有成員名字應是區分大小寫的。 函式、方法、過程都可以認為是可以互換的。

客戶端被定義為請求物件的來源及響應物件的處理程式。

服務端被定義為響應物件的起源和請求物件的處理程式。

該規範的一種實現為可以輕而易舉的填補這兩個角色,即使是在同一時間,同一客戶端或其他不相同的客戶端。 該規範不涉及複雜層。

3.相容性

JSON-RPC 2.0 的請求物件和響應物件可能無法在現用的JSON-RPC 1.0 客戶端或服務端工作，然而我們可以很容易在兩個版本間區分出2.0，總會包含一個成員命名為 “jsonrpc” 且值為“2.0”， 而1.0版本是不包含的。大部分的2.0實現應該考慮嘗試處理1.0的物件，即使不是對等的也應給其相關提示。

4.請求物件

傳送一個請求物件至服務端代表一個rpc呼叫， 一個請求物件包含下列成員：

jsonrpc

指定JSON-RPC協議版本的字串，必須準確寫為“2.0”

method

包含所要呼叫方法名稱的字串，以rpc開頭的方法名，用英文句號（U+002E or ASCII 46）連線的為預留給rpc內部的方法名及副檔名，且不能在其他地方使用。

params

呼叫方法所需要的結構化引數值，該成員引數可以被省略。

id

已建立客戶端的唯一標識id，值必須包含一個字串、數值或NULL空值。如果不包含該成員則被認定為是一個通知。該值一般不為NULL[1]，若為數值則不應該包含小數[2]。

服務端必須回答相同的值如果包含在響應物件。 這個成員用來兩個物件之間的關聯上下文。

1
在請求物件中不建議使用NULL作為id值，因為該規範將使用空值認定為未知id的請求。另外，由於JSON-RPC 1.0 的通知使用了空值，這可能引起處理上的混淆。

[2]
使用小數是不確定性的，因為許多十進位制小數不能精準的表達為二進位制小數。

4.1通知

沒有包含“id”成員的請求物件為通知，
作為通知的請求物件表明客戶端對相應的響應物件並不感興趣，本身也沒有響應物件需要返回給科幻的。服務端必須不回覆一個通知，包含那些批量請求中的。

由於通知沒有返回的響應物件，所以通知不確定是否被定義。同樣，客戶端不會意識到任何錯誤（例如引數預設，內部錯誤）。

4.2引數結構

rpc呼叫如果存在引數則必須為基本型別或結構化型別的引數值，要麼為索引陣列，要麼為關聯陣列物件。

  • 索引：引數必須為陣列，幷包含與服務端預期順序一致的引數值。

  • 關聯名稱：引數必須為物件，幷包含與服務端相匹配的引數成員名稱。沒有在預期中的成員名稱可能會引起錯誤。名稱必須完全匹配，包括方法的預期引數名以及大小寫。

5.響應物件

當發起一個rpc呼叫時，除通知之外，服務端都必須回覆響應。響應表示為一個JSON物件，使用以下成員：

jsonrpc

指定JSON-RPC協議版本的字串，必須準確寫為“2.0”

result

該成員在成功時必須包含。

當呼叫方法引起錯誤時必須不包含該成員。

服務端中的被呼叫方法決定了該成員的值。

error

該成員在失敗是必須包含。

當沒有引起錯誤的時必須不包含該成員。

該成員引數值必須為5.1中定義的物件。

id

該成員必須包含。

該成員值必須於請求物件中的id成員值一致。

若在檢查請求物件id時錯誤（例如引數錯誤或無效請求），則該值必須為空值。

響應物件必須包含result或error成員，但兩個成員必須不能同時包含。

5.1錯誤物件

當一個rpc呼叫遇到錯誤時，返回的響應物件必須包含錯誤成員引數，並且為帶有下列成員引數的物件：

code

使用數值表示該異常的錯誤型別。
必須為整數。

message

對該錯誤的簡單描述字串。
該描述應儘量限定在簡短的一句話。

data

包含關於錯誤附加資訊的基本型別或結構化型別。該成員可忽略。
該成員值由服務端定義（例如詳細的錯誤資訊，巢狀的錯誤等）。

-32768至-32000為保留的預定義錯誤程式碼。在該範圍內的錯誤程式碼不能被明確定義，保留下列以供將來使用。錯誤程式碼基本與XML-RPC建議的一樣，url：
http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

code message meaning
-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服務端錯誤 預留用於自定義的伺服器錯誤。

除此之外剩餘的錯誤型別程式碼可供應用程式作為自定義錯誤。

6.批量呼叫

當需要同時傳送多個請求物件時，客戶端可以傳送一個包含所有請求物件的陣列。

當批量呼叫的所有請求物件處理完成時，服務端則需要返回一個包含相對應的響應物件陣列。每個響應物件都應對應每個請求物件，除非是通知的請求物件。服務端可以併發的，以任意順序和任意寬度的並行性來處理這些批量呼叫。

這些相應的響應物件可以任意順序的包含在返回的陣列中，而客戶端應該是基於各個響應物件中的id成員來匹配對應的請求物件。

若批量呼叫的rpc操作本身非一個有效json或一個至少包含一個值的陣列，則服務端返回的將單單是一個響應物件而非陣列。若批量呼叫沒有需要返回的響應物件，則服務端不需要返回任何結果且必須不能返回一個空陣列給客戶端。

7.示例

Syntax:

--> data sent to Server
<-- data sent to Client

帶索引陣列引數的rpc呼叫:

--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

--> {"jsonrpc": "2.0", "method": "subtract", "params": [23, 42], "id": 2}
<-- {"jsonrpc": "2.0", "result": -19, "id": 2}

帶關聯陣列引數的rpc呼叫:

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"subtrahend": 23, "minuend": 42}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 4}
<-- {"jsonrpc": "2.0", "result": 19, "id": 4}

通知:

--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}
--> {"jsonrpc": "2.0", "method": "foobar"}

不包含呼叫方法的rpc呼叫:

--> {"jsonrpc": "2.0", "method": "foobar", "id": "1"}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "1"}

包含無效json的rpc呼叫:

--> {"jsonrpc": "2.0", "method": "foobar, "params": "bar", "baz]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}

包含無效請求物件的rpc呼叫:

--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

包含無效json的rpc批量呼叫:

--> [
        {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
        {"jsonrpc": "2.0", "method"
    ]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}

包含空陣列的rpc呼叫:

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

非空且無效的rpc批量呼叫:

--> [1]
<-- [
    {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}
    ]

無效的rpc批量呼叫:

--> [1,2,3]
<-- [
    {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
    {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
    {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}
    ]

rpc批量呼叫:

--> [
    {"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"}
    ]

所有都為通知的rpc批量呼叫:

--> [
    {"jsonrpc": "2.0", "method": "notify_sum", "params": [1,2,4]},
    {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]}
]

<-- //Nothing is returned for all notification batches

7.擴充套件

以rpc開頭的方法名預留作為系統擴充套件，且必須不能用於其他地方。每個系統擴充套件都應該有相關規範文件，所有系統擴充套件都應是可選的。

Copyright (C) 2007-2010 by the JSON-RPC Working Group

This document and translations of it may be used to implement JSON-RPC, it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not bemodified in any way.

相關文章