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 結構示例（“-->”表示傳送，“<--”表示響應，下同）： ```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 物件，使用以下成員： - jsonrpc：指定 JSON-RPC 協議版本的字串，必須準確寫為“2.0”。 - result：呼叫成功時響應給客戶端的結果，當呼叫發生錯誤時可以不包含該成員。 - error：呼叫發生錯誤時返回給客戶端的錯誤資訊，在呼叫失敗時必須包含該成員。 - id：對應請求物件的“id”，其值必須與請求物件中的“id”值一致。 響應物件必須包含 result 或 error 成員之一。 響應物件的 error 成員的結構包含下列成員： - code：使用數值表示該異常的錯誤型別，必須為整數。、 - message：對該錯誤的簡單描述字串，該描述應儘量限定在簡短的一句話。 - data：包含關於錯誤的附加資訊，可忽略。 其中 -32768 至 -32000 為保留的預定義錯誤程式碼，各保留錯誤程式碼的含義請檢視文末參考連結[1]。 下面是幾個響應物件的 JSON 結構示例： ```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 結構示例： ```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](https://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](https://www.jsonrpc.org/specification) [2].[github.com/microsoft/vs-streamjsonrpc](https://github.com/microsoft/vs-streamjsonrpc)