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

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

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

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

📦 專案來源：[jsonrpc-sample on GitHub](https://github.com/jeff377/jsonrpc-sample)

---

## 🧱 為何選擇 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.Business`、`Bee.Db`：業務與資料存取層
- 支援資料傳輸的完整編碼流程（序列化 → 壓縮 → 加密）

---

## 🧰 實作 JSON-RPC Server 與 Client

### Step 1：準備 `System.Settings.xml`

設定內容包含：

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

---

### Step 2：定義傳入參數及回傳結果的類別（Custom.Define）

public class HelloArgs { public string UserName { get; set; } }
public class HelloResult { public string Message { get; set; } }

---

### Step 3：實作業務邏輯（Custom.Business）

public class EmployeeBusinessObject
{
    public HelloResult Hello(HelloArgs args)
    {
        return new HelloResult { Message = $"Hello, {args.UserName}" };
    }
}

### Step 4：ProgId 對應業務邏輯物件
實作 IBusinessObjectProvider.CreateFormBusinessObject 方法，判斷 ProgId 建立對應的業務邏輯物件

public IFormBusinessObject CreateFormBusinessObject(Guid accessToken, string progId)
{
    switch (progId)
    {
        case "Employee":
            return new EmployeeBusinessObject(accessToken, progId);
        default:
            return new FormBusinessObject(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 HelloArgs() { UserName = "Jeff" };
var result = connector.Execute<HelloResult>("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.HelloArgs, 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.NET` 的 `Connector` 自動產生並包裝，開發者無需手動組裝 JSON，但瞭解其結構有助於除錯與跨平台整合。

---

### 🌐 API 呼叫情境

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

#### 1. 內部系統呼叫（高效最佳化）

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

#### 2. 第三方系統整合（開放且簡潔）

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

---
## ✅ 結語

透過 `Bee.NET` 的模組設計與 JSON-RPC 支援，我們能：

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

## 📚 延伸閱讀

- [企業系統的 N-Tier 架構設計](https://hackmd.io/@jeff377/enterprise-n-tier)
- [基於企業系統架構的 .NET 開發框架](https://hackmd.io/@jeff377/bee-net-framework)
- [JSON-RPC vs gRPC vs REST 技術比較表](https://hackmd.io/@jeff377/jsonrpc-grpc-rest-comparison)
- [Protobuf vs MessagePack 序列化格式比較](https://hackmd.io/@jeff377/protobuf-vs-messagepack)

---
**📢 歡迎轉載，請註明出處**
**📬 歡迎追蹤我的技術筆記與實戰經驗分享**
[Facebook](https://www.facebook.com/profile.php?id=61574839666569) ｜ [HackMD](https://hackmd.io/@jeff377) ｜ [GitHub](https://github.com/jeff377) ｜ [NuGet](https://www.nuget.org/profiles/jeff377)