RPC通道 · UBot平臺中文文檔

# RPC通道 ## 數據包 UBot的所有RPC數據包均使用[JSON-RPC 2.0](http://wiki.geekdream.com/Specification/json-rpc_2.0.html)進行編碼 >[warning] UBot只能處理標準JSON，注釋等擴展內容將導致解析失敗！數據包示例： ```json // Request // 存在id字段（即使為null）表示常規請求 // 不存在id字段表示通知模式，服務端只會處理請求，不會給予回應 { "json-rpc":"2.0", "id":55, "method":"get_user_name", "params":[ "Account1", "123456789" ] } // Response { "id":55, "jsonrpc":"2.0", "result":"UBotTest" } ``` ## 命名規范所有RPC操作的方法名、參數名均使用蛇形命名法(Snake Case) 示例： ``` hello_world get_token ``` 所有RPC參數，如非特別聲明，均按位置調用 ```json {params:["hello","world"]} //按位置調用 {params:{"a":"hello","b":"world"}} //按名稱調用 ``` ## 通訊協議 UBot的所有RPC都是全雙工類型的RPC，即Router可以調用客戶端的函數，客戶端也可以調用Router的函數從`JSON-RPC 2.0`規范的角度來講，無論是傳輸層的服務端還是客戶端，都同時是`JSON-RPC 2.0`中所講的Server和Client RPC支持以下幾種連接方式 >[warning] 盡管可以同時使用多種方式（同時存在多個連接），但**極度不推薦**這么做 ### Websocket 模式所有的UBot RPC都支持且推薦使用Websocket協議連接 - 全雙工模式：直接連接 >[info] 任何情況下，都應該首選該模式 - Server-Client模式：在URL中加入參數`norequest=1`，此時客戶端可以向Router發送請求，但Router不會向客戶端發送任何請求（如觸發事件），Router只會回應客戶端的請求 >[info] 此模式往往用于難以實現Peer模式的平臺，通過建立兩個Websocket連接，一個負責向Router發送請求，另一個負責接收來自Router的請求 ### HTTP Post 模式通過向RPC連接發送POST請求，提交內容為請求信息(`application/json`)，返回內容為響應信息(`application/json`)或空（對于`JSON-RPC`中定義的通知而言，不作任何響應）該模式只能向Router發送請求，無法接收請求請求示例： ``` // Request POST /api/app?id=Echo&token=Ciq-h4_7TV26egu0aPBi1A HTTP/1.1 Content-Length: 130 Content-Type: application/json Host: localhost:5000 { "json-rpc":"2.0", "id":0, "method":"get_user_name", "params":[ "Account", "1234" ] } // Response HTTP/1.1 200 OK Content-Length: 46 Content-Type: application/json; charset=utf-8 {"id":0,"jsonrpc":"2.0","result":"HelloWorld"} ``` ### Webhook 模式通過注冊Webhook，在Router向客戶端發出請求時，自動Post某個網址，并將返回結果作為JSON-RPC的響應對象該模式只能接收Router的請求，無法**主動**向Router發出任何請求如果您接收到的是請求對象，您必須返回JSON-RPC的響應對象，除非您接收到的是通知您可以通過返回一個同時包含響應對象和請求對象的數組來**被動**地向Router發出請求（這些請求的響應結果又會作為數據以webhook的形式調度給您，您可以繼續回復請求對象向Router繼續發送請求。如果您不需要回應，則可以使用`JSON-RPC`中定義的通知模式發出請求） #### Webhook 管理請參考API列表Webhook控制器部分 ## RPC庫 JSON-RPC 2.0是使用較廣泛的一種協議，全雙工模式（即Peer模式，部分庫只支持Server-Client模式）也是較常見的一種實現方式，大部分平臺都可以找到支持over Websocket的庫 - Golang平臺：[wsrpc](https://github.com/1354092549/wsrpc) - .NET平臺：[microsoft/vs-streamjsonrpc](https://github.com/microsoft/vs-streamjsonrpc) - Node.js平臺：[json-rpc-peer](https://github.com/JsCommunity/json-rpc-peer) - Dart平臺：[dart-lang/json_rpc_2](https://github.com/dart-lang/json_rpc_2) >[info] 以上RPC庫并非由本人維護，若遇到問題請咨詢對應作者