在 Bee.NET
架構中,API 採用「約定型別」(Convention-based Types)與 $type
型別標記模式,達成模組化設計與型別安全,同時兼顧彈性與防禦性。本文說明如何設計 API 方法參數與安全的 JSON-RPC 反序列化策略,打造可維護、可擴充且具高安全性的企業系統架構。
Args
類別(輸入)與一個 Result
類別(輸出)$type
欄位,明確指明型別優點 | 說明 |
---|---|
向前相容 | 可新增屬性並設定預設值,不影響舊版相容性 |
型別安全 | 強型別設計,降低傳錯資料或誤用風險 |
流程統一 | 序列化、驗證、日誌與加解密等可共用基礎設計 |
易於測試與維護 | 結構清晰,方便進行模組化測試與維護 |
文件自動化 | 可結合 Swagger 或 DocFX 自動生成 API 文件 |
挑戰項目 | 說明 |
---|---|
學習曲線 | 需理解命名慣例與封裝邏輯 |
類型數量增加 | 每個方法需額外定義 Args/Result,命名與管理需規範 |
不適合極簡操作 | 若僅需傳遞單一欄位,封裝類別略顯冗長 |
反序列化風險 | 必須控管允許反序列化的型別來源,避免安全漏洞 |
為防止反序列化攻擊(Deserialization Attack),要求所有透過 $type
傳遞的型別資訊,皆必須來自受信任的命名空間。這項機制確保系統只會反序列化已知且安全的資料物件(DTO),有效阻止任意程式邏輯被觸發。
系統僅允許 $type
對應的型別來自預設或設定檔指定的命名空間:
預設自動允許以下命名空間,不須額外設定:
Bee.Base
Bee.Define
這種設計不僅簡化部署流程,也避免遺漏必要命名空間。
僅允許來自信任命名空間的純資料物件(DTO)進行反序列化,所有 $type
指定的型別皆必須符合以下條件:
Bee.Define
, Custom.Define
)的型別Bee.NET
採用 $type
型別標記與命名空間白名單設計,在兼顧彈性與維護性的前提下,有效防堵反序列化攻擊,是建構高安全性 API 架構的關鍵設計策略。
📢 歡迎轉載,請註明出處
📬 歡迎追蹤我的技術筆記與實戰經驗分享
Facebook | HackMD | GitHub | NuGet