(譯) JSON-RPC 2.0 規範(中文版)

時間  2019-12-05
標籤 json rpc 2.0 規範 中文版 欄目 JavaScript 简体版
原文   原文鏈接

本文博客wiki地址:http://wiki.geekdream.com/Specification/json-rpc_2.0.htmlphp

1.概述

JSON-RPC是一個無狀態且輕量級的遠程過程調用(RPC)協議。 本規範主要定義了一些數據結構及其相關的處理規則。它容許運行在基於socket,http等諸多不一樣消息傳輸環境的同一進程中。其使用JSON（RFC 4627）做爲數據格式。html

它爲簡單而生!json

2.約定

文檔中關鍵字"MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、"RECOMMENDED"、"MAY"和 "OPTIONAL" 將在RFC 2119 中獲得詳細的解釋及描述。數組

因爲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也要大寫。服務器

在客戶端與任何被匹配到的服務端之間交換的全部成員名字應是區分大小寫的。 函數、方法、過程均可以認爲是能夠互換的。數據結構

客戶端被定義爲請求對象的來源及響應對象的處理程序。併發

服務端被定義爲響應對象的起源和請求對象的處理程序。socket

該規範的一種實現爲能夠垂手可得的填補這兩個角色,即便是在同一時間,同一客戶端或其餘不相同的客戶端。 該規範不涉及複雜層。ide

3.兼容性

JSON-RPC 2.0 的請求對象和響應對象可能沒法在現用的JSON-RPC 1.0 客戶端或服務端工做，然而咱們能夠很容易在兩個版本間區分出2.0，總會包含一個成員命名爲 「jsonrpc」 且值爲「2.0」， 而1.0版本是不包含的。大部分的2.0實現應該考慮嘗試處理1.0的對象，即便不是對等的也應給其相關提示。函數

4.請求對象

發送一個請求對象至服務端表明一個rpc調用， 一個請求對象包含下列成員：

jsonrpc

指定JSON-RPC協議版本的字符串，必須準確寫爲「2.0」

method

包含所要調用方法名稱的字符串，以rpc開頭的方法名，用英文句號（U+002E or ASCII 46）鏈接的爲預留給rpc內部的方法名及擴展名，且不能在其餘地方使用。

params

調用方法所須要的結構化參數值，該成員參數能夠被省略。

id

已創建客戶端的惟一標識id，值必須包含一個字符串、數值或NULL空值。若是不包含該成員則被認定爲是一個通知。該值通常不爲NULL[1]，若爲數值則不該該包含小數[2]。

服務端必須回答相同的值若是包含在響應對象。 這個成員用來兩個對象之間的關聯上下文。

1
在請求對象中不建議使用NULL做爲id值，由於該規範將使用空值認定爲未知id的請求。另外，因爲JSON-RPC 1.0 的通知使用了空值，這可能引發處理上的混淆。

[2]
使用小數是不肯定性的，由於許多十進制小數不能精準的表達爲二進制小數。

4.1通知

沒有包含「id」成員的請求對象爲通知，
做爲通知的請求對象代表客戶端對相應的響應對象並不感興趣，自己也沒有響應對象須要返回給科幻的。服務端必須不回覆一個通知，包含那些批量請求中的。

因爲通知沒有返回的響應對象，因此通知不肯定是否被定義。一樣，客戶端不會意識到任何錯誤（例如參數缺省，內部錯誤）。

4.2參數結構

rpc調用若是存在參數則必須爲基本類型或結構化類型的參數值，要麼爲索引數組，要麼爲關聯數組對象。

  • 索引：參數必須爲數組，幷包含與服務端預期順序一致的參數值。

  • 關聯名稱：參數必須爲對象，幷包含與服務端相匹配的參數成員名稱。沒有在預期中的成員名稱可能會引發錯誤。名稱必須徹底匹配，包括方法的預期參數名以及大小寫。

5.響應對象

當發起一個rpc調用時，除通知以外，服務端都必須回覆響應。響應表示爲一個JSON對象，使用如下成員：

jsonrpc

指定JSON-RPC協議版本的字符串，必須準確寫爲「2.0」

result

該成員在成功時必須包含。

當調用方法引發錯誤時必須不包含該成員。

服務端中的被調用方法決定了該成員的值。

error

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

當沒有引發錯誤的時必須不包含該成員。

該成員參數值必須爲5.1中定義的對象。

id

該成員必須包含。

該成員值必須於請求對象中的id成員值一致。

若在檢查請求對象id時錯誤（例如參數錯誤或無效請求），則該值必須爲空值。

響應對象必須包含result或error成員，但兩個成員必須不能同時包含。

5.1錯誤對象

當一個rpc調用遇到錯誤時，返回的響應對象必須包含錯誤成員參數，而且爲帶有下列成員參數的對象：

code

使用數值表示該異常的錯誤類型。
必須爲整數。

message

對該錯誤的簡單描述字符串。
該描述應儘可能限定在簡短的一句話。

data

包含關於錯誤附加信息的基本類型或結構化類型。該成員可忽略。
該成員值由服務端定義（例如詳細的錯誤信息，嵌套的錯誤等）。

-32768至-32000爲保留的預約義錯誤代碼。在該範圍內的錯誤代碼不能被明肯定義，保留下列以供未來使用。錯誤代碼基本與XML-RPC建議的同樣，url：
http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

code message meaning
-32700 Parse error語法解析錯誤 服務端接收到無效的json。該錯誤發送於服務器嘗試解析json文本
-32600 Invalid Request無效請求 發送的json不是一個有效的請求對象。
-32601 Method not found找不到方法 該方法不存在或無效
-32602 Invalid params無效的參數 無效的方法參數。
-32603 Internal error內部錯誤 JSON-RPC內部錯誤。
-32000 to -32099 Server error服務端錯誤 預留用於自定義的服務器錯誤。

除此以外剩餘的錯誤類型代碼可供應用程序做爲自定義錯誤。

6.批量調用

當須要同時發送多個請求對象時，客戶端能夠發送一個包含全部請求對象的數組。

當批量調用的全部請求對象處理完成時，服務端則須要返回一個包含相對應的響應對象數組。每一個響應對象都應對應每一個請求對象，除非是通知的請求對象。服務端能夠併發的，以任意順序和任意寬度的並行性來處理這些批量調用。

這些相應的響應對象能夠任意順序的包含在返回的數組中，而客戶端應該是基於各個響應對象中的id成員來匹配對應的請求對象。

若批量調用的rpc操做自己非一個有效json或一個至少包含一個值的數組，則服務端返回的將單單是一個響應對象而非數組。若批量調用沒有須要返回的響應對象，則服務端不須要返回任何結果且必須不能返回一個空數組給客戶端。

7.示例

Syntax:

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

帶索引數組參數的rpc調用:

--> {"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調用:

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

包含無效請求對象的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調用:

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

<-- //Nothing is returned for all notification batches

7.擴展

以rpc開頭的方法名預留做爲系統擴展，且必須不能用於其餘地方。每一個系統擴展都應該有相關規範文檔，全部系統擴展都應是可選的。

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.

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程