# 在 N-Tier 架構下的跨層 Trace 與近端模擬


🔗 GitHub 原始碼：<https://github.com/jeff377/bee-library>

在企業系統開發中，常見的 N-Tier 架構會將 UI、API、Business、Db 等層拆分並跨伺服器部署。
這種分層雖然能提升可維護性與擴充性，但也帶來挑戰：**跨層 Trace 難以一次性觀測完整流程**。

BeeNET 提供的 **Trace 機制** 與 **JSON-RPC 近端連線模擬**，正是為了解決這個問題：

- 讓開發者能清楚掌握作業流程與耗時分佈
- 協助快速定位效能瓶頸
- 在開發環境中完成「一次性 Trace」，再對照正式環境找出問題

---

## 1️⃣ 架構背景

BeeNET 採五層式 **N-Tier 架構**：

UI → Connect → API → Business (BO) → Db → 資料庫

- **前端**：WinForms、MAUI、Blazor
- **API 呼叫層**：Bee.Connect 封裝近端/遠端呼叫
- **後端 API**：Bee.Api.* 接收 JSON-RPC 請求
- **業務邏輯層**：Bee.Business（BusinessObject / FormBusinessObject）
- **資料層**：Bee.Db 封裝 SQL 與資料庫操作

Trace 的價值在於協助開發者：

- 掌握作業流程與呼叫層級
- 確認哪些 BO 負責處理動作
- 分析跨層與分段耗時
- 快速定位效能瓶頸或錯誤來源

---

## 2️⃣ Trace 機制

### 🔑 核心元件

| 類別 | 功能 |
|------|------|
| `Tracer` | 提供 `Start` / `End` / `Write` 建立追蹤事件 |
| `TraceContext` | 保存層級、名稱、細節與計時器 |
| `TraceEvent` | 結構化事件（Start / End / Point，含耗時與狀態） |
| `TraceLayer` | 區分 UI、ApiClient、ApiServer、Business、Data |
| `TraceListener` | 監控器，呼叫 `ITraceWriter` 輸出事件 |
| `ITraceWriter` | 輸出介面，可實作檔案、Console 或 UI 顯示 |
| `FormTraceWriter` | 範例：WinForms Trace Viewer |

---

### ⚙️ 使用方式

#### ① 啟用 Trace

SysInfo.TraceListener = new TraceListener(new FormTraceWriter(form));

#### ② 區段追蹤

var ctx = Tracer.Start(TraceLayer.Business, "SubmitOrder", "開始送單");
try {
    _orderBo.Validate(orderId);
    _orderBo.Persist(orderId);
    Tracer.End(ctx, TraceStatus.Ok);
}
catch (Exception ex) {
    Tracer.End(ctx, TraceStatus.Error, ex.Message);
    throw;
}

#### ③ 單點事件

Tracer.Write(TraceLayer.Data, "SQL", "Execute SaveOrder", TraceStatus.Ok);

---

### 📊 輸出內容

每筆事件包含：

- **Time**：發生時間
- **Layer**：層級（UI、ApiClient、ApiServer、Business、Data）
- **Name**：動作名稱
- **Detail**：額外描述（如 SQL、API 路由）
- **DurationMs**：耗時（僅區段 End 有值）
- **Status**：執行結果（Ok、Error、Cancelled）
- **Kind**：事件類型（Start、End、Point）

---

### 🚀 案例：效能問題定位

案例：使用者回報「建立訂單很慢」。

Trace Tree 顯示：

ApiServer.SubmitOrder (310ms)
 └─ Business.OrderBo.Persist (240ms)
     └─ Data.SqlOrderRepository.Save (220ms)

👉 瓶頸在資料層，應優先檢查 SQL 與索引。

---

### 🧭 Trace 解讀實務

1. **確認流程**：依事件順序觀察呼叫路徑
2. **責任定位**：檢查 BO/Repository，知道由誰處理
3. **效能分析**：比較各區段耗時，找出最慢的環節
4. **錯誤處理**：觀察 `Status=Error` 事件，搭配統一例外訊息規範，快速定位問題

---

## 3️⃣ JSON-RPC 近端連線

### 為什麼需要？

利用 JSON-RPC「近端連線模擬」把跨機器流程拉回本機，完成端到端 Trace，讓開發人員能完整觀測 UI → Connect → API → BO → DB 的流程。

- **正式環境**：前端與後端分離，呼叫經過 HTTP/HTTPS，Trace 被拆成兩段
- **開發環境**：利用 LocalMode 直呼 BO，呼叫流程不經網路堆疊，整條流程跑在同一行程，Trace 覆蓋全層

### 模式比較
- **遠端模式**：UI → Connect（HTTP/HTTPS）→ API Server → BO → DB
- **近端模式**：UI → Connect（直呼 BO）→ BO → DB
- 保留 JSON-RPC 封裝，確保程式碼路徑一致
- Trace 可一次涵蓋 UI → BO → DB

---

## ✅ 結論

- BeeNET 的 Trace 機制能精確記錄流程、責任歸屬與耗時
- JSON-RPC **近端連線模擬** 可在開發環境完成「一次性 Trace」，快速鎖定瓶頸
- 正式環境再切回遠端模式，對照 Trace 資料即可判斷問題是程式邏輯還是網路/部署

---
**📢 歡迎轉載，請註明出處**
**📬 歡迎追蹤我的技術筆記與實戰經驗分享**
[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)