在 Bee.NET 架構中，API 採用「約定型別」（Convention-based Types）與 $type 型別標記模式，達成模組化設計與型別安全，同時兼顧彈性與防禦性。本文說明如何設計 API 方法參數與安全的 JSON-RPC 反序列化策略，打造可維護、可擴充且具高安全性的企業系統架構。

🧩 設計核心原則

• 每個 API 方法對應一個 Args 類別（輸入）與一個 Result 類別（輸出）
• 所有輸入參數封裝為類別，以支援版本向前相容（可加欄位）
• 僅允許反序列化指定命名空間（透過白名單）內的型別
• 所有 JSON 傳輸物件需包含 $type 欄位，明確指明型別

/// <summary>
/// 登入系統。
/// </summary>
public LoginResult Login(LoginArgs args)
{    
}

/// <summary>
/// 登入系統的傳入引數。
/// </summary>
public class LoginArgs
{
    public string UserId { get; set; }
    public string Password { get; set; }
    public string Language { get; set; } = "zh-TW";
}

/// <summary>
/// 登入系統的傳出結果。
/// </summary>
public class LoginResult
{
    public Guid AccessToken { get; set; }
    public DateTime ExpiredAt { get; set; }
}

✅ 採用約定型別的好處

❌ 可能的挑戰

✅ 型別白名單機制與安全策略

為防止反序列化攻擊（Deserialization Attack），要求所有透過 $type 傳遞的型別資訊，皆必須來自受信任的命名空間。這項機制確保系統只會反序列化已知且安全的資料物件（DTO），有效阻止任意程式邏輯被觸發。

限制允許反序列化的命名空間

系統僅允許 $type 對應的型別來自預設或設定檔指定的命名空間：

<Settings>
  <AllowedTypeNamespaces>
    <Namespace>Custom.Define</Namespace>
  </AllowedTypeNamespaces>
</Settings>

預設安全命名空間

預設自動允許以下命名空間，不須額外設定：

• Bee.Base
• Bee.Define

AllowedTypeNamespaces = new List<string>
{
    "Bee.Base",
    "Bee.Define",
    // 來自設定檔的其他命名空間
};

這種設計不僅簡化部署流程，也避免遺漏必要命名空間。

✅ 型別反序列化安全原則

僅允許來自信任命名空間的純資料物件（DTO）進行反序列化，所有 $type 指定的型別皆必須符合以下條件：

• 所有 DTO 型別皆為預先定義的資料物件，僅包含屬性，無任何執行邏輯
• 執行期間不會觸發任何自動化方法或反射邏輯
• 僅允許來自指定命名空間（如 Bee.Define, Custom.Define）的型別
• 在防禦攻擊的同時，保有 RPC 設計的彈性與可擴充性

📌 小結

Bee.NET 採用 $type 型別標記與命名空間白名單設計，在兼顧彈性與維護性的前提下，有效防堵反序列化攻擊，是建構高安全性 API 架構的關鍵設計策略。

📘 HackMD 原文筆記：
👉 https://hackmd.io/@jeff377/api-parameter-design

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