在企業級系統架構中，API 不僅是前後端溝通的主要橋樑，也是資料存取與業務流程運行的核心通道。然而在實務上，API 的安全性管理往往面臨多項挑戰：

• 不同 API 可能需要不同的安全等級與存取條件。
• 第三方系統接入時，需平衡便利性與安全性。
• 安全檢查分散在各處，導致維護困難與程式碼重複。
• 當安全策略改變時，需要大量修改既有程式。

在傳統設計中，許多開發團隊會在 Controller 或 Service 中手動撰寫驗證邏輯，例如驗證登入、檢查金鑰、判斷是否加密等。
這種方式雖然直觀，但隨著系統成長會造成程式碼分散、重複且難以統一調整。

為了解決這些問題，我們在 Bee.NET 中設計了一套 宣告式 API 存取控制機制，透過 特性（Attribute） 搭配 驗證器（Validator），將安全性邏輯集中管理並自動化執行。

📦 範例程式：jsonrpc-sample

🎯 設計理念

Bee.NET 將 API 方法分離到服務層，由框架統一處理安全性驗證，而非讓每個方法自行檢查。這樣有幾個好處：

1. 集中管理：存取條件集中於方法宣告處，減少重複驗證程式碼。
2. 可讀性高：透過屬性（Attribute）即可直觀了解該方法的存取限制。
3. 易於擴充：未來若新增驗證條件，只需擴充驗證邏輯，不必修改每個方法。
4. 跨平台一致性：無論是 WinForms、Blazor、MAUI 前端，皆可套用相同規範，確保一致性。

🔐 存取控制屬性設計

/// <summary>
/// 標註 API 方法的存取控制屬性
/// </summary>
[AttributeUsage(AttributeTargets.Method, Inherited = true)]
public class ApiAccessControlAttribute : Attribute
{
    // 存取保護等級（編碼與加密需求）
    public ApiProtectionLevel ProtectionLevel { get; }
    
    // 存取授權需求（是否需要登入）
    public ApiAccessRequirement AccessRequirement { get; }
}

🔑 API 存取保護等級（ApiProtectionLevel）

🔑 API 存取授權需求（ApiAccessRequirement）

🔍 存取驗證流程

這套流程確保在進入業務邏輯層前，所有安全性檢查都已完成，避免未授權或不安全的請求進入系統核心。

📌 使用範例

public class UserApi
{
    /// <summary>
    /// 取得當前使用者資訊（需登入，需加密）
    /// </summary>
    [ApiAccessControl(ApiProtectionLevel.Encrypted, ApiAccessRequirement.Authenticated)]
    public UserInfo GetCurrentUser() { /* ... */ }

    /// <summary>
    /// 系統健康檢查（匿名可呼叫）
    /// </summary>
    [ApiAccessControl(ApiProtectionLevel.Public, ApiAccessRequirement.Anonymous)]
    public string Ping() => "OK";
}

💡 維運與擴充優勢

• 策略集中：任何安全策略變更，只需在 Validator 實作中調整一次。
• 可測試性高：驗證邏輯可單獨測試，不需透過完整 API 呼叫。
• 跨平台適用：不論前端是桌面、Web 或行動應用，都可套用一致規範。

結語

此機制會部署在 API 服務層（Bee.Api.Core.dll），作為 所有 API 入口的第一道防線，在進入業務邏輯層（Bee.Business.dll）前先完成安全性驗證。
這樣能確保 無論是 WinForms、Blazor、MAUI 前端 呼叫 API，都遵循相同的安全規範，同時減少程式碼重複與維護負擔。

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

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