Web服务实现方案四：JSON-RPC简介

 

参考：https://zh.wikipedia.org/wiki/XML-RPC

 

JSON-RPC是一种远程过程调用 协议中的编码JSON。这是一个非常简单的协议，（非常类似于XML-RPC），只定义数据类型和命令的屈指可数。JSON-RPC允许通知（发送到不需要响应的服务器数据）和用于多个呼叫将被发送到可被回答无序服务器。

 

历史

版 描述 过时的

1.0	蓝本	2005年
1.1 WD	工作草案增加了命名参数，增加了特定的错误代码，并添加了内省功能。	2006-08-07
1.1 Alt键	建议一个简单的JSON-RPC 1.1替代建议1.1 WD。	2007-05-06
1.1对象规格	对象规范替代建议1.1 WD / 1.1ALT。	2007-07-30
1.2	建议本文档的修订后更名为2.0。	2007-12-27
2.0	建议规范	2009-05-24
2.0（Revised-）	规范	2010-03-26

使用

JSON-RPC的工作原理是发送给实施这一协议的服务器发送请求。在这种情况下，客户机通常是软件意图调用远程系统的一个方法。多个输入参数可以被传递到作为数组或对象的远程方法，而该方法本身可以返回多个输出数据为好。（这取决于所实现的版本）。

远程方法是通过使用发送请求到远程服务调用HTTP或TCP / IP的套接字（从2.0版）。当使用HTTP，所述内容类型可以被定义为应用/ JSON。^[1]

所有的传输类型的单个对象，使用JSON序列化。^[2]请求是由远程系统所提供的特定方法的调用。它必须包含三个特定的属性：

• 方法 -该方法的名称的字符串被调用。
• PARAMS -对象的数组作为参数来定义的方法传递。
• 编号 -的任何类型的，它被用来以匹配它答复请求的响应的值。

请求的接收器必须对所有接收到的请求的有效响应回复。的响应必须包含以下提到的属性。

• 结果 -通过调用方法返回的数据。如果在调用方法时发生错误，则此值必须为空。
• 错误 -如果在调用方法的错误，否则指定的错误代码空。
• 编号 -这是响应请求的ID。

由于有在需要甚至期望没有反应的情况下，被引入的通知。通知是类似于除了ID，这是不是必要的，因为没有任何反应会返回一个请求。在这种情况下的id属性应被删去（版本2.0）或为空（1.0版）。

 

Examples

In these examples, --> denotes data sent to a service (request), while <-- denotes data coming from a service. (Although <-- often is called response in client–server computing, depending on the JSON-RPC version it does not necessarily imply answer to a request).

Version 1.0

A simple request and response:

--> {"method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
<-- {"result": "Hello JSON-RPC", "error": null, "id": 1}

This example shows parts of a communication from an example chat application. The chat service sends notifications for each chat message the client peer should receive. The client peer sends requests to post messages to the chat and expects a positive reply to know the message has been posted.

...
--> {"method": "postMessage", "params": ["Hello all!"], "id": 99}
<-- {"result": 1, "error": null, "id": 99}
<-- {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
<-- {"method": "handleMessage", "params": ["user3", "sorry, gotta go now, ttyl"], "id": null}
--> {"method": "postMessage", "params": ["I have a question:"], "id": 101}
<-- {"method": "userLeft", "params": ["user3"], "id": null}
<-- {"result": 1, "error": null, "id": 101}
...

Because params field is an array of objects, the following format is also ok:

{
    "method": "methodnamehere",
    "params": [
        {
            "firstparam": "this contains information of the firstparam.",
            "secondparam": 1121211234,
            "thirdparam": "this contains information of the thirdparam."
        },
        {
            "fourthparam": "this is already a different object.",
            "secondparam": "there can be same name fields in different objects.",
            "thirdparam": "this contains information of the thirdparam."
        }
    ],
    "id": 1234
}

Version 1.1 (Working Draft)

The format of the contents of a request might be something like that shown below:

{
    "version": "1.1",
    "method": "confirmFruitPurchase",
    "id": "194521489",
    "params": [
        ["apple", "orange", "mangoes"],
        1.123
    ]
}

The format of a response might be something like this:

{
    "version": "1.1",
    "result": "done",
    "error": null,
    "id": "194521489"
}

Version 2.0

Procedure 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}

Procedure call with named parameters:

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

Notification:

--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}

--> {"jsonrpc": "2.0", "method": "foobar"}

Procedure call of non-existent procedure:

--> {"jsonrpc": "2.0", "method": "foobar", "id": 10}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Procedure not found."}, "id": 10}

Procedure call with invalid JSON:

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

Procedure call with invalid JSON-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}
]

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