.NET 開源項目 StreamJsonRpc 介紹 [上篇]

StreamJsonRpc 是一個實作了 JSON-RPC 通信協定的開源 .NET 庫，在介紹 StreamJsonRpc 之前，我們先來了解一下 JSON-RPC。

JSON-RPC 介紹

JSON-RPC 是一個無狀态且輕量級的遠端過程調用（RPC）協定，其使用 JSON（RFC 4627）作為資料格式。

目前 JSON-RPC 的版本已發展到 2.0，JSON-RPC 2.0 與 1.0 的約定規範是不一樣的。2.0 包含一個名為

jsonrpc

且值為

2.0

的成員，而 1.0 版本是不包含的。是以我們可以很容易在兩個版本間區分出 2.0。

JSON-RPC 在用戶端與服務端之間交換的所有成員名應是區分大小寫的，函數、方法、過程都認為是可互換的。用戶端被定義為請求對象的來源及響應對象的處理程式；服務端被定義為響應對象的起源和請求對象的處理程式。

請求對象

發送一個請求對象至服務端代表一個 RPC 調用，JSON-RPC 2.0 規定一個請求對象包含下列成員：

• jsonrpc：指定 JSON-RPC 協定版本的字元串，必須準确寫為“2.0”。
• method：包含所要調用方法名稱的字元串，以 rpc 開頭的方法名，用英文句号連接配接的為預留給 rpc 内部的方法名及擴充名，且不能在其他地方使用。
• params：調用方法所需要的結構化參數值，該成員參數可以被省略。
• id：已建立用戶端的唯一辨別，值必須包含一個字元串、數值或 NULL 空值。如果不包含該成員則被認定為是一個通知。該值一般不為 NULL，若為數值則不應該包含小數。

沒有包含

id

成員的請求對象為通知，作為通知的請求對象表明用戶端對服務端響應不感興趣，服務端可以不響應請求對象給用戶端。

下面是幾個請求對象的 JSON 結構示例（“-->”表示發送，“<--”表示響應，下同）：

--> { "jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1 }
--> { "jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 4}
--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]} // 通知
           

響應對象

當用戶端發起一個 RPC 調用時，除通知之外，服務端都必須回複響應。響應也表示為一個 JSON 對象，使用以下成員：

• result：調用成功時響應給用戶端的結果，當調用發生錯誤時可以不包含該成員。
• error：調用發生錯誤時傳回給用戶端的錯誤資訊，在調用失敗時必須包含該成員。
• id：對應請求對象的“id”，其值必須與請求對象中的“id”值一緻。

響應對象必須包含 result 或 error 成員之一。

響應對象的 error 成員的結構包含下列成員：

• code：使用數值表示該異常的錯誤類型，必須為整數。、
• message：對該錯誤的簡單描述字元串，該描述應盡量限定在簡短的一句話。
• data：包含關于錯誤的附加資訊，可忽略。

其中 -32768 至 -32000 為保留的預定義錯誤代碼，各保留錯誤代碼的含義請檢視文末參考連結[1]。

下面是幾個響應對象的 JSON 結構示例：

<-- {"jsonrpc": "2.0", "result": 19, "id": 1}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "1"}
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null} // 無效調用
           

批量調用

當需要同時發送多個請求對象時，用戶端可以發送一個包含所有請求對象的數組。

當批量調用的所有請求對象處理完成時，服務端則需要傳回一個包含相對應的響應對象數組。每個響應對象都應對應每個請求對象，除非是通知的請求對象。服務端可以并發的，可以以任意順序和任意寬度并行處理這些批量調用。而用戶端應該是基于各個響應對象中的 id 成員來比對對應的請求對象。

若批量調用沒有需要傳回的響應對象，則服務端不需要傳回任何結果。

下面是一個批量請求及響應的 JSON 結構示例：

--> [
      {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
      {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
      {"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", "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"}
    ]
           

當批量請求對象都是通知時，服務端不需要傳回結果。

StreamJsonRpc 庫介紹

StreamJsonRpc 是一個實作了 JSON-RPC 通信協定的 .NET 庫，支援 .NET Core。它把 RPC 的調用封裝為公開的 .NET API，可以很友善的進行 RPC 請求的發送和接收操作。StreamJsonRpc 是微軟官方的一個開源庫，目前 Star 數接近 300，貌似知道的人不多或者用的人不多。GitHub 位址：

github.com/microsoft/vs-streamjsonrpc

StreamJsonRpc 可以在 Stream、WebSocket 或 System.IO.Pipelines 管道上工作，獨立于底層傳輸。除了包含 JSON-RPC 規範所需的特性外，它額外還有如下優點：

• 請求取消
• .NET 事件作為通知
• 動态用戶端代理生成
• 支援緊湊的 MessagePack 二進制序列化
• 易于實作插件式架構的消息處理和格式化

使用 StreamJsonRpc 主要有四個基本步驟：建立 JSON-RPC 連接配接、發送 RPC 請求、接收 RPC 請求、斷開連接配接。

這一篇主要介紹一些預備知識，下一篇将通過示例示範并詳細介紹 StreamJsonRpc 的使用，敬請期待！

參考：

[1].jsonrpc.org/specification

[2].github.com/microsoft/vs-streamjsonrpc

作者：精緻碼農-王亮

出處：http://cnblogs.com/willick

聯系：[email protected]

本文版權歸作者和部落格園共有，歡迎轉載，但未經作者同意必須保留此段聲明，且在文章頁面明顯位置給出原文連接配接，否則保留追究法律責任的權利。如有問題或建議，請多多賜教，非常感謝。