Try   HackMD

JSON‑RPC 架構實作:近端除錯 vs 遠端部署的最佳實踐

在企業系統開發中,API 架構扮演關鍵角色。它不僅是前後端溝通的橋樑,更是跨模組、跨服務協作的核心。相較於 REST 著重資源導向、gRPC 聚焦高效能與嚴格協定,JSON-RPC 則提供一種更靈活且結構化的方案:以方法為核心設計,格式輕量、請求與 JSON 高度相容,極適合需要明確業務流程邏輯的應用系統。

除了架構彈性,JSON-RPC 更具備資料編碼上的延展性。在 Bee.NET 的設計中,JSON-RPC 的資料傳輸流程可支援 MessagePack 序列化、壓縮與加密,確保資料在內部系統或跨網路傳輸時兼顧「效能」、「安全」與「易於維護」。相較於 protobuf,MessagePack 在動態物件結構與 .NET 環境中更具開發友善性,且不需維護 .proto 檔案,開發流程更簡潔。

Bee.NET 架構同時支援「近端除錯」與「遠端部署」兩種呼叫模式,能大幅提升開發效率並降低部署成本。本文將以 jsonrpc-sample 專案為例,展示如何構建一套模組化、可維護、具備資料編碼與雙模式呼叫能力的 JSON‑RPC 架構。

📦 專案來源:jsonrpc-sample on GitHub


🧱 為何選擇 N‑Tier 架構與近/遠端雙模式?

在企業級系統(如 ERP/HRM)中,常見的 N‑Tier 架構會將應用程式邏輯分層:

  1. 表現層(UI)
  2. API Connector 層(處理呼叫與資料封裝)
  3. API Service 層(處理驗證、例外)
  4. 業務邏輯層(核心流程邏輯)
  5. 資料存取層(DB 存取)

這樣的架構具備以下優勢:

  • 模組分離、開發維護容易
  • 可切換 近端開發除錯(直連 DLL)與 遠端部署呼叫(透過 JSON-RPC)
  • 資料傳輸可整合序列化、壓縮、加密處理,提升安全與效能

🐝 Bee.NET 的架構設計理念簡介

以「模組分工」為設計主軸,具備以下核心元件:

  • Bee.Connect:支援近端/遠端雙模式 JSON-RPC 呼叫
  • Bee.Api.AspNetCore:處理 JSON-RPC API 請求
  • Bee.BusinessBee.Db:業務與資料存取層
  • 支援資料傳輸的完整編碼流程(序列化 → 壓縮 → 加密)

🧰 實作 JSON-RPC Server 與 Client

Step 1:準備 System.Settings.xml

設定內容包含:

  • AllowedTypeNamespaces:限制反序列化來源,防止反序化攻擊
  • ApiPayloadOptions:定義 API 傳遞資料的序列化、壓縮、加密方法
  • BusinessObjectProvider:指定業務邏輯物件載入方式

Step 2:定義傳入參數及回傳結果的類別(Custom.Define)

public class THelloArgs { public string UserName { get; set; } }
public class THelloResult { public string Message { get; set; } }

Step 3:實作業務邏輯(Custom.Business)

public class TEmployeeBusinessObject
{
    public THelloResult Hello(THelloArgs args)
    {
        return new THelloResult { Message = $"Hello, {args.UserName}" };
    }
}

Step 4:ProgId 對應業務邏輯物件

實作 IBusinessObjectProvider.CreateFormBusinessObject 方法,判斷 ProgId 建立對應的業務邏輯物件

public IFormBusinessObject CreateFormBusinessObject(Guid accessToken, string progId)
{
    switch (progId)
    {
        case "Employee":
            return new TEmployeeBusinessObject(accessToken, progId);
        default:
            return new TFormBusinessObject(accessToken, progId);
    }
}

Step 5:啟動 JSON-RPC Server(JsonRpcServer)

app.BackendInitialize(app.Configuration);

Step 6:撰寫 JSON-RPC Client(JsonRpcClient)

透過 Connecotr 指定 ProgId 連接對應的業務邏輯物件,執行指定方法。

var connector = ClientInfo.CreateFormApiConnector("Employee");
var args = new THelloArgs() { UserName = "Jeff" };
var result = connector.Execute<THelloResult>("Hello", args);
Console.WriteLine($"Message: {result.Message}");

可在開發時切換為「近端」模式,直接載入 DLL 呼叫,除錯更便利。


💬 JSON-RPC 請求格式示例

以下為 Hello 方法的 JSON-RPC 呼叫範例,使用 POST 傳送:

{
  "jsonrpc": "2.0",
  "method": "Employee.Hello",
  "params": {
    "value": {
      "$type": "Custom.Define.THelloArgs, Custom.Define",
      "userName": "Jeff"
    }
  },
  "id": "uuid"
}

📌 說明:

  • "jsonrpc": "2.0":指定使用 JSON-RPC 2.0 協議版本
  • "method":格式為 ProgID.Method,此例為 Employee.Hello
  • "params.value":實際傳入的參數物件
  • "$type":為 .NET 反序列化時所需型別資訊(含命名空間與組件)
  • "id":用於請求/回應配對的識別碼,可為 UUID、整數或字串

此格式將由 Bee.NETConnector 自動產生並包裝,開發者無需手動組裝 JSON,但瞭解其結構有助於除錯與跨平台整合。


🌐 API 呼叫情境

Bee.NET 所建構的 JSON-RPC 架構設計,支援以下兩種主要情境:

1. 內部系統呼叫(高效最佳化)

企業內部的開發程式(如 WinForms/WPF、行動應用、後端服務等)可透過 Connector 類別呼叫 API,支援近端與遠端雙模式,並自動處理參數的序列化、壓縮與加密,提供一致、最佳化的呼叫體驗。

2. 第三方系統整合(開放且簡潔)

對於外部系統或異質平台,亦可使用標準 HTTP POST 呼叫 JSON-RPC 接口,傳送未編碼的 JSON 原始格式。透過明確的參數結構與型別註記,實現跨平台整合需求。


✅ 結語

透過 Bee.NET 的模組設計與 JSON-RPC 支援,我們能:

  • 快速建置 N-Tier 架構
  • 靈活切換開發與部署模式
  • 強化資料傳輸效率與安全性

📚 延伸閱讀


📢 歡迎轉載,請註明出處
📬 歡迎追蹤我的技術筆記與實戰經驗分享
FacebookHackMDGitHubNuGet