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开关的方法名保留作系统扩展。其它不论什么地方都必须不能使用。
每一个系统扩展都定义在相关的规范中。全部系统扩展都是可选的。
