# 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）
```csharp
public class HelloArgs { public string UserName { get; set; } }
public class HelloResult { public string Message { get; set; } }
```
---
### Step 3：實作業務邏輯（Custom.Business）
```csharp
public class EmployeeBusinessObject
{
public HelloResult Hello(HelloArgs args)
{
return new HelloResult { Message = $"Hello, {args.UserName}" };
}
}
```
### Step 4：ProgId 對應業務邏輯物件
實作 IBusinessObjectProvider.CreateFormBusinessObject 方法，判斷 ProgId 建立對應的業務邏輯物件
```csharp
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）
```csharp
app.BackendInitialize(app.Configuration);
```
---
### Step 6：撰寫 JSON-RPC Client（JsonRpcClient）
透過 Connecotr 指定 ProgId 連接對應的業務邏輯物件，執行指定方法。
```csharp
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 傳送：
```json
{
"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)
Sign in via Google
Sign in via Facebook
Sign in via X(Twitter)
Sign in via GitHub
Sign in via Dropbox
Sign in with Wallet
Connect another wallet