json-rpc2.0协议

概览

JSON-RPC是一种无状态，轻量级远程程序调用协议。不只一种数据结构及其处理规则可以符合这种定义。数据通过socket,http,或其他环境传输，并不能确定其将在本进程内使用。他使用json来作为数据格式

约定

关键词“MUST”, "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "OPTIONAL"的解释可以在RFC2119中找到。

由于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也要大写。

兼容

JSON-RPC 2.0定义的请求对象和响应对象和现有的JSON-RPC 1.0客户端/服务器有兼容问题。这两个版本其实很好区分，2.0定义了一个叫"jsonrpc"的成员，其值时2.0，而1.0版本没有。2.0的实现往往要兼容1.0的对象，即使我们在开发点对点以外或者明显不是1.0的业务的时候亦是如此。

请求对象

发送一个请求至服务端代表一个rpc调用，一个请求对象包含下列成员

jsonrpc

指定JSON-RPC协议版本的字符串，必须准确写为'2.0'

method

包含所要调用方法名称的字符串，以rpc开头的方法名，用英文句号连接的为预留给rpc内部的方法名及扩展名，且不能再其他地方使用。

params

调用方法所需要的结构化参数值，该成员参数可以被省略。

id

已建立客户端的唯一标识id,值必须包含一个字符串、数值或NULL空值。如果不包含该成员则被认定为为是一个通知。该值一般不为NULL,若数值则不应该包含小数。

通知

当请求参数中不发送id成员时，该请求会被当作通知处理。对于通知，客户端不关心响应对象，因为服务端也没必要返回响应对象，确切的说，服务端不准答复一个通知请求，即便这个请求是批处理请求中的一个。
根据这个定义，通知请求并不会被确认，因为客户端不会收到响应对象，更进一步说，通知请求的客户端无法感知到错误，比如参数错误/网络错误等。

参数结构

rpc调用如果存在参数则必须为基本类型或结构化类型的参数值，要么为索引数组，要么为关联数组对象。

• 索引： 参数必须为数组，并包含于服务端预期顺序一致的参数值
• 关联名称：参数必须为对象，并包含于服务端相匹配的参数成员名称。没有在预期中的成员名称可能会引起错误。名称必须完全匹配，包括方法的预期参数名及大小写。

响应对象

发起一个rpc调用时，除通知之外，服务端都必须回复响应。响应表示为一个JSON对象，使用以下成员：

jsonrpc

指定JSON-RPC协议版本的字符串，必须准确写为'2.0'

result

该成员在成功时必须包含
当调用方法引起错误是必须不包含该成员
服务端中的被调用方法决定了该成员的值

error

该成员在失败是必须包含
当没有引起错误的时必须不包含该成员
该成员参数值必须为5.1中定义的对象

id

该成员必须包含
该成员值必须与请求对象中的id成员值一直
若在检查请求对象id是错误（例如参数错误或无效请求），则该值必须为空值。

错误对象

当一个rpc调用遇到错误时，返回的响应对象必须包含错误成员参数哦，并且为带有下列成员参数的对象：

code

使用数据表示该异常的错误类型
必须为整数
对该错误的简单描述字符串
该描述应尽量限定在简短的依据话

data

包含关于错误附加信息的基本类型或结构化类型。该成员可忽略。
该成员值由服务端定义（列如详细的错误信息，嵌套的错误等）。
-32768至-32000为保留的预定义错误代码。在该范围内的错误代码不能被明确定义，保留下列以供将来使用。错误代码基本与XML-RPC建议的一样，url：
http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php