# API 方法的存取控管設計


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

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

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

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

📦 範例程式：[jsonrpc-sample](https://github.com/jeff377/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）

| 值 | 說明 | 使用時機 |
|----|------|----------|
| **Public** | 一般開放：允許任何呼叫，不強制編碼，開放給第三方 | 健康檢查、公開 API |
| **Encoded** | 需要編碼：允許遠端呼叫，但必須序列化與壓縮 | 需減少傳輸量，但不涉及敏感資料 |
| **Encrypted** | 需要加密：允許遠端呼叫，必須序列化、壓縮並加密 | 涉及敏感資料或金流交易 |
| **LocalOnly** | 僅限近端呼叫（不驗證編碼） | 內部工具程式、背景服務調用 |

---

## 🔑 API 存取授權需求（ApiAccessRequirement）

| 值 | 說明 | 使用時機 |
|----|------|----------|
| **Anonymous** | 不需登入（Anonymous Access） | 公開查詢、登入 API、健康檢查 |
| **Authenticated** | 需要登入（驗證 AccessToken） | 讀取或操作使用者專屬資料、後台管理功能 |

---

## 🔍 存取驗證流程

flowchart TD
    A[API 呼叫進入] --> B[取得 ApiAccessControlAttribute]
    B -->|未標註| X[拒絕存取]
    B -->|已標註| D[檢查 AccessRequirement]
    D -->|需要登入| E[驗證 AccessToken]
    D -->|匿名可呼叫| G[檢查 ProtectionLevel]
    E -->|無效| X
    E -->|有效| G[檢查 ProtectionLevel]
    G -->|Public| C[進入業務邏輯層]
    G -->|Encoded| H[驗證編碼]
    G -->|Encrypted| I[驗證加密與金鑰]
    G -->|LocalOnly| J[檢查是否近端呼叫]
    H -->|失敗| X
    I -->|失敗| X
    J -->|否| X
    H -->|通過| C
    I -->|通過| C
    J -->|是| C

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

---

## 📌 使用範例

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，都遵循相同的安全規範，同時減少程式碼重複與維護負擔。