JSON-RPC 2.0 規(guī)范中文版 - 無狀態(tài)輕量級遠程過程調用協(xié)議

• 起源時間: 2010-03-26(基于2009-05-24版本)
• 更新: 2013-01-04
• 作者: JSON-RPC工作組< json-rpc@googlegroups.com >
• 原文鏈接: www.jsonrpc.org/specification
• 翻譯: leozvc < xxfs91@gmail.com >

1.概述

JSON-RPC是一個無狀態(tài)且輕量級的遠程過程調用(RPC)協(xié)議。 本規(guī)范主要定義了一些數(shù)據(jù)結構及其相關的處理規(guī)則。它允許運行在基于socket,http等諸多不同消息傳輸環(huán)境的同一進程中。其使用JSON（RFC 4627）作為數(shù)據(jù)格式。

它為簡單而生!

2.約定

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

由于JSON-RPC使用JSON，它具有與其相同的類型系統(tǒng)(見www.json.org或RFC 4627)。JSON可以表示四個基本類型(String、Numbers、Booleans和Null)和兩個結構化類型(Objects和Arrays)。 規(guī)范中，術語“Primitive”標記那4種原始類型，“Structured”標記兩種結構化類型。任何時候文檔涉及JSON數(shù)據(jù)類型，第一個字母都必須大寫：Object，Array，String，Number，Boolean，Null。包括True和False也要大寫。

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

客戶端被定義為請求對象的來源及響應對象的處理程序。

服務端被定義為響應對象的起源和請求對象的處理程序。

該規(guī)范的一種實現(xiàn)為可以輕而易舉的填補這兩個角色,即使是在同一時間,同一客戶端或其他不相同的客戶端。 該規(guī)范不涉及復雜層。

3.兼容性

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

4.請求對象

發(fā)送一個請求對象至服務端代表一個rpc調用， 一個請求對象包含下列成員：

jsonrpc

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

method

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

params

調用方法所需要的結構化參數(shù)值，該成員參數(shù)可以被省略。

id

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

服務端必須回答相同的值如果包含在響應對象。 這個成員用來兩個對象之間的關聯(lián)上下文。

[1] 在請求對象中不建議使用NULL作為id值，因為該規(guī)范將使用空值認定為未知id的請求。另外，由于JSON-RPC 1.0 的通知使用了空值，這可能引起處理上的混淆。

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

4.1通知

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

由于通知沒有返回的響應對象，所以通知不確定是否被定義。同樣，客戶端不會意識到任何錯誤（例如參數(shù)缺省，內部錯誤）。

4.2參數(shù)結構

rpc調用如果存在參數(shù)則必須為基本類型或結構化類型的參數(shù)值，要么為索引數(shù)組，要么為關聯(lián)數(shù)組對象。

• 索引：參數(shù)必須為數(shù)組，并包含與服務端預期順序一致的參數(shù)值。
• 關聯(lián)名稱：參數(shù)必須為對象，并包含與服務端相匹配的參數(shù)成員名稱。沒有在預期中的成員名稱可能會引起錯誤。名稱必須完全匹配，包括方法的預期參數(shù)名以及大小寫。

5.響應對象

當發(fā)起一個rpc調用時，除通知之外，服務端都必須回復響應。響應表示為一個JSON對象，使用以下成員：

jsonrpc

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

result

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

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

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

error

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

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

該成員參數(shù)值必須為5.1中定義的對象。

id

該成員必須包含。

該成員值必須于請求對象中的id成員值一致。

若在檢查請求對象id時錯誤（例如參數(shù)錯誤或無效請求），則該值必須為空值。

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

5.1錯誤對象

當一個rpc調用遇到錯誤時，返回的響應對象必須包含錯誤成員參數(shù)，并且為帶有下列成員參數(shù)的對象：

code

使用數(shù)值表示該異常的錯誤類型。 必須為整數(shù)。

message

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

data

包含關于錯誤附加信息的基本類型或結構化類型。該成員可忽略。 該成員值由服務端定義（例如詳細的錯誤信息，嵌套的錯誤等）。

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

除此之外剩余的錯誤類型代碼可供應用程序作為自定義錯誤。

6.批量調用

當需要同時發(fā)送多個請求對象時，客戶端可以發(fā)送一個包含所有請求對象的數(shù)組。

當批量調用的所有請求對象處理完成時，服務端則需要返回一個包含相對應的響應對象數(shù)組。每個響應對象都應對應每個請求對象，除非是通知的請求對象。服務端可以并發(fā)的，以任意順序和任意寬度的并行性來處理這些批量調用。

這些相應的響應對象可以任意順序的包含在返回的數(shù)組中，而客戶端應該是基于各個響應對象中的id成員來匹配對應的請求對象。

若批量調用的rpc操作本身非一個有效json或一個至少包含一個值的數(shù)組，則服務端返回的將單單是一個響應對象而非數(shù)組。若批量調用沒有需要返回的響應對象，則服務端不需要返回任何結果且必須不能返回一個空數(shù)組給客戶端。

7.示例

Syntax:

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

帶索引數(shù)組參數(shù)的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}

帶關聯(lián)數(shù)組參數(shù)的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}

包含空數(shù)組的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開頭的方法名預留作為系統(tǒng)擴展，且必須不能用于其他地方。每個系統(tǒng)擴展都應該有相關規(guī)范文檔，所有系統(tǒng)擴展都應是可選的。

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.

本頁面的文字允許在知識共享 署名-相同方式共享 3.0協(xié)議和GNU自由文檔許可證下修改和再使用