JSON-RPC 2.0 規(guī)范中文版 - 無(wú)狀態(tài)輕量級(jí)遠(yuǎn)程過(guò)程調(diào)用協(xié)議

• 起源時(shí)間: 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是一個(gè)無(wú)狀態(tài)且輕量級(jí)的遠(yuǎn)程過(guò)程調(diào)用(RPC)協(xié)議。 本規(guī)范主要定義了一些數(shù)據(jù)結(jié)構(gòu)及其相關(guān)的處理規(guī)則。它允許運(yùn)行在基于socket,http等諸多不同消息傳輸環(huán)境的同一進(jìn)程中。其使用JSON（RFC 4627）作為數(shù)據(jù)格式。

它為簡(jiǎn)單而生!

2.約定

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

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

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

客戶端被定義為請(qǐng)求對(duì)象的來(lái)源及響應(yīng)對(duì)象的處理程序。

服務(wù)端被定義為響應(yīng)對(duì)象的起源和請(qǐng)求對(duì)象的處理程序。

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

3.兼容性

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

4.請(qǐng)求對(duì)象

發(fā)送一個(gè)請(qǐng)求對(duì)象至服務(wù)端代表一個(gè)rpc調(diào)用， 一個(gè)請(qǐng)求對(duì)象包含下列成員：

jsonrpc

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

method

包含所要調(diào)用方法名稱的字符串，以rpc開(kāi)頭的方法名，用英文句號(hào)（U+002E or ASCII 46）連接的為預(yù)留給rpc內(nèi)部的方法名及擴(kuò)展名，且不能在其他地方使用。

params

調(diào)用方法所需要的結(jié)構(gòu)化參數(shù)值，該成員參數(shù)可以被省略。

id

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

服務(wù)端必須回答相同的值如果包含在響應(yīng)對(duì)象。 這個(gè)成員用來(lái)兩個(gè)對(duì)象之間的關(guān)聯(lián)上下文。

[1] 在請(qǐng)求對(duì)象中不建議使用NULL作為id值，因?yàn)樵撘?guī)范將使用空值認(rèn)定為未知id的請(qǐng)求。另外，由于JSON-RPC 1.0 的通知使用了空值，這可能引起處理上的混淆。

[2] 使用小數(shù)是不確定性的，因?yàn)樵S多十進(jìn)制小數(shù)不能精準(zhǔn)的表達(dá)為二進(jìn)制小數(shù)。

4.1通知

沒(méi)有包含“id”成員的請(qǐng)求對(duì)象為通知， 作為通知的請(qǐng)求對(duì)象表明客戶端對(duì)相應(yīng)的響應(yīng)對(duì)象并不感興趣，本身也沒(méi)有響應(yīng)對(duì)象需要返回給客戶端。服務(wù)端必須不回復(fù)一個(gè)通知，包含那些批量請(qǐng)求中的。

由于通知沒(méi)有返回的響應(yīng)對(duì)象，所以通知不確定是否被定義。同樣，客戶端不會(huì)意識(shí)到任何錯(cuò)誤（例如參數(shù)缺省，內(nèi)部錯(cuò)誤）。

4.2參數(shù)結(jié)構(gòu)

rpc調(diào)用如果存在參數(shù)則必須為基本類(lèi)型或結(jié)構(gòu)化類(lèi)型的參數(shù)值，要么為索引數(shù)組，要么為關(guān)聯(lián)數(shù)組對(duì)象。

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

5.響應(yīng)對(duì)象

當(dāng)發(fā)起一個(gè)rpc調(diào)用時(shí)，除通知之外，服務(wù)端都必須回復(fù)響應(yīng)。響應(yīng)表示為一個(gè)JSON對(duì)象，使用以下成員：

jsonrpc

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

result

該成員在成功時(shí)必須包含。

當(dāng)調(diào)用方法引起錯(cuò)誤時(shí)必須不包含該成員。

服務(wù)端中的被調(diào)用方法決定了該成員的值。

error

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

當(dāng)沒(méi)有引起錯(cuò)誤的時(shí)必須不包含該成員。

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

id

該成員必須包含。

該成員值必須于請(qǐng)求對(duì)象中的id成員值一致。

若在檢查請(qǐng)求對(duì)象id時(shí)錯(cuò)誤（例如參數(shù)錯(cuò)誤或無(wú)效請(qǐng)求），則該值必須為空值。

響應(yīng)對(duì)象必須包含result或error成員，但兩個(gè)成員必須不能同時(shí)包含。

5.1錯(cuò)誤對(duì)象

當(dāng)一個(gè)rpc調(diào)用遇到錯(cuò)誤時(shí)，返回的響應(yīng)對(duì)象必須包含錯(cuò)誤成員參數(shù)，并且為帶有下列成員參數(shù)的對(duì)象：

code

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

message

對(duì)該錯(cuò)誤的簡(jiǎn)單描述字符串。 該描述應(yīng)盡量限定在簡(jiǎn)短的一句話。

data

包含關(guān)于錯(cuò)誤附加信息的基本類(lèi)型或結(jié)構(gòu)化類(lèi)型。該成員可忽略。 該成員值由服務(wù)端定義（例如詳細(xì)的錯(cuò)誤信息，嵌套的錯(cuò)誤等）。

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

除此之外剩余的錯(cuò)誤類(lèi)型代碼可供應(yīng)用程序作為自定義錯(cuò)誤。

6.批量調(diào)用

當(dāng)需要同時(shí)發(fā)送多個(gè)請(qǐng)求對(duì)象時(shí)，客戶端可以發(fā)送一個(gè)包含所有請(qǐng)求對(duì)象的數(shù)組。

當(dāng)批量調(diào)用的所有請(qǐng)求對(duì)象處理完成時(shí)，服務(wù)端則需要返回一個(gè)包含相對(duì)應(yīng)的響應(yīng)對(duì)象數(shù)組。每個(gè)響應(yīng)對(duì)象都應(yīng)對(duì)應(yīng)每個(gè)請(qǐng)求對(duì)象，除非是通知的請(qǐng)求對(duì)象。服務(wù)端可以并發(fā)的，以任意順序和任意寬度的并行性來(lái)處理這些批量調(diào)用。

這些相應(yīng)的響應(yīng)對(duì)象可以任意順序的包含在返回的數(shù)組中，而客戶端應(yīng)該是基于各個(gè)響應(yīng)對(duì)象中的id成員來(lái)匹配對(duì)應(yīng)的請(qǐng)求對(duì)象。

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

7.示例

Syntax:

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

帶索引數(shù)組參數(shù)的rpc調(diào)用:

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

帶關(guān)聯(lián)數(shù)組參數(shù)的rpc調(diào)用:

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

不包含調(diào)用方法的rpc調(diào)用:

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

包含無(wú)效json的rpc調(diào)用:

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

包含無(wú)效請(qǐng)求對(duì)象的rpc調(diào)用:

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

包含無(wú)效json的rpc批量調(diào)用:

--> [
        {"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調(diào)用:

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

非空且無(wú)效的rpc批量調(diào)用:

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

無(wú)效的rpc批量調(diào)用:

--> [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批量調(diào)用:

--> [
    {"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批量調(diào)用:

--> [
    {"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.擴(kuò)展

以rpc開(kāi)頭的方法名預(yù)留作為系統(tǒng)擴(kuò)展，且必須不能用于其他地方。每個(gè)系統(tǒng)擴(kuò)展都應(yīng)該有相關(guān)規(guī)范文檔，所有系統(tǒng)擴(kuò)展都應(yī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.

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