🔗 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 機制

🔑 核心元件

⚙️ 使用方式

① 啟用 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 資料即可判斷問題是程式邏輯還是網路/部署

📘 HackMD 原文筆記：
👉 https://hackmd.io/@jeff377/ntier-trace

📢 歡迎轉載，請註明出處
📬 歡迎追蹤我的技術筆記與實戰經驗分享
Facebook ｜ HackMD ｜ GitHub ｜ NuGet