JSON-RPC 2.0规范 翻译 中文版

JSON-RPC 2.0规范

起源日期：

2010-03-26（基于2009-05-24的版本号）

修正：

2013-01-04

作者：

JSON-RPC 工作组 <json-rpc@googlegroups.com>

1 概述

JSON-RPC是一个无状态的、轻量级的远程过程调用（RPC）协议。本规范主要环绕它的处理方式定义了几个数据结构和规则。这个概念可用于在同一进程中、套接字或HTTP之间、或其它非常多消息传递的环境中数据传输。它使用JSON (RFC 4627)作为数据格式。

JSON-RPC的设计非常easy！

2 约定

本文档中的关键词“必须”、“必须不”、“要求”、“会”、“不会”、“应该”、“不应该”、“推荐”、“可能”和“可选的”与RFC 2119中翻译同样。

因为JSON-RPC使用JSON格式，它拥有与JSON相同的类型系统（见http://www.json.org 或 RFC 4627）。JSON能够表示4种原始类型（字符串、数值、布尔和Null）和两种结构化类型（对象和数组）。

术语“原始类型”在本文档中代表这四种原始JSON类型中的随意一种。术语“结构化类型”代表结构化的JSON类型。

本文档中的随意JSON类型，首字母总是大写：Object、Array、String、Number、Boolean、Null。True和False首字母相同是大写的。

client和server端交换的全部成员名字都是大写和小写敏感的。术语函数、方法和过程都觉得是可交换的。

client被定义成原始请求对象和响应对象处理器。

server被定义成原始响应对象和请求对象处理器。

本规范的实现能够非常easy的满足这些要求。即使对于其它不同的client或同样的client。

本规范没有解决那一层次的复杂性。

3 兼容性

JSON-RPC 2.0请求对象和响应对象可能与已经存在的JSON-RPC1.0client或server端不兼容。然而。非常easy区分两个版本号，由于2.0版本号总是包括一个名为“jsonrpc”的成员。其值为字符串“2.0”，而1.0版本号不存在。大多数2.0版本号的实现应该考虑处理1.0版本号的对象，即使不是对等的，也应该给予良好的提示。

4 请求对象

发送一个请求对象到server表示一个RPC调用。

请求对象包含以下这些成员：

jsonrpc

指定JSON-RPC版本号的字符串，它必须是“2.0”。

method

调用的方法的名字。以rpc开头方法名表示rpc内部的方法和扩展，其它地方必须不能使用。

params

它是一个结构化的值，持有方法调用期间的參数值。该成员可省略。

id

client建立的一个标识符。假设请求中包括这个成员的话，它必须是字符串、数值或NULL值。假设没有包括该成员。那么它被觉得是一个通知。这个值一般不应该为Null^[1]而且假设是数值的话不应该包括小数部分^[2]。

假设client包括了id成员，那么server端必须包括相同的值在响应对象中。这个成员用于关联请求和响应这两个对象之间的上下文。

[1]不推荐在请求对象中使用Null作为id成员的值。由于本规范使用Null值作为对一个未知id的值。

相同。由于JSON-RPC 1.0使用id值为Null来作为通知，在处理时这可能引起混淆。

[2]小数部分可能导致总是，由于非常多小数不能被精确的表示成二进制形式。

4.1 通知

假设请求对象中没有“id”成员，则表示一个通知。通知请求对象表示client对对应的响应对象不感兴趣，因此不须要返回响应对象给client。server必须不回复一个通知，即使是在批量请求中。

因为不会返回响应对象，所以通知不easy定义。

因此，client不会知道有不论什么错误（像：“无效的參数”、“内部错误”等）。

4.2 结构化參数

rpc调用假设存在參数，那么必须提供结构化的參数值。要么通过一个数组的位置，要么通过一个对象的名字。

通过位置：參数必须是一个数组。包括server期望的顺序的值。

通过名字：參数必须是一个对象，对象的成员名与server期望的參数名匹配。缺少期望的參数名可能导致错误。

名字必须精确匹配，包含与方法期望的參数名的大写和小写。

5 响应对象

当发起rpc调用时，server必须回复一个响应，通知除外。

响应被表示成一个单一的对象。包括下列的成员：

jsonrpc

指定JSON-RPC版本号的字符串，它必须是“2.0”。

result

当调用成功时，该成员是必须的。

假设调用方法出现错误时，必须不包括该成员。

该成员的值由server上调用的方法决定。

error

当调用错误发生时，该成员是必须的。

在调用期间假设没有错误产生，必须不包括该成员。

该成员的值必须是一个5.1节定义的对象。

id

该成员是必须的。

它的值必须与请求对象中的id成员的值同样。

假设检查请求对象中的id时错误发生（如：转换错误或无效的请求）。它必须为Null。

必须包括result或error成员，可是两个成员都必须不能同一时候包括。

5.1 错误对象

当一个rpc调用遇到错误时，响应对象必须包括一个值为对象的error成员，该对象包括下列的成员：

code

一个数字。表示错误发生的类型。

这个成员值必须是整型。

message

提供简短错误描写叙述的字符串。

message应该限制为一个简短的句子。

data

原始类型或结构化类型值。包括了关于错误的附加信息。

这个成员能够省略。

该成员的值由server端定义（如：具体的错误信息，嵌套的错误信息等）。

错误代码值-32768到-32000为保留值，作为提前定义错误。这个范围内的不论什么代码。但在下表中未定义的值。保留作未来使用。这些错误代码差点儿与下列地址中XML-RPC建议的同样（ http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php）。

代码	消息	含义
-32700	解析错误	server接收到无效的JSON。 server解析JSON文本错误发生。
-32600	无效的请求	发送的JSON不是一个有效的请求。
-32601	方法未找到	方法不存在或不可见。
-32602	无效的參数	无效的方法參数。
-32603	内部错误	JSON-RPC内部错误。
-32000 to -32099	server端错误	保留给详细实现定义server端错误。

应用程序能够使用剩下的代码来定义错误。

6 批量调用

为了同一时候发送多个请求对象，client能够发送一个请求对象数组。

在全部批量请求对象都处理完毕后，server应该使用一个数组作为响应，数组中包括相应的响应对象。每一个请求对象都应该相应一个响应对象，像通知这样不应该有响应对象的除外。server能够以不论什么宽度的并行性，以随意的顺序，并发地处理一个批量rpc调用。

批量调用能够使用数组以随意的顺序返回响应对象。client可通过每一个对象中包括的id成员在一系列请求对象和响应对象之间进行匹配。

假设批量rpc调用本身发生无效的JSON或一个至少包括一个值的数组导致失败，server生成的响应必须是一个单一的响应对象。假设发送到client的响应数组中不包括响应对象，那么server必须不能返回一个空的数组。而应该不返回不论什么东西。

7 演示样例

语法：

--> 表示数据发送到server端

<-- 表示数据发送到client

位置參数形式的rpc调用：

rpc call with positional parameters:

--> {"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调用

rpc call with invalid JSON:

--> {"jsonrpc":"2.0", "method": "foobar, "params":"bar", "baz]

<-- {"jsonrpc": "2.0", "error":{"code": -32700, "message": "Parse error"},"id": null}

rpc call with invalid Request object:

无效请求对象的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 call with an empty Array:

--> []

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

    ]

<-- //批量通知调用什么也不返回

8 扩展

以rpc开关的方法名保留作系统扩展。其它不论什么地方都必须不能使用。

每一个系统扩展都定义在相关的规范中。全部系统扩展都是可选的。