使用組件與可重用性

在軟體開發中，重複使用是效率和一致性的關鍵。API 設計也不例外。您不應該一遍又一遍地重新定義相同的錯誤回應、參數或資料結構，而應該只定義一次並在各處重複使用它們。

在本章中，我們將學習如何使用 Apidog 的 元件系統 來建立可重複使用的資產。我們將為我們的 Pet Store User 模組定義參數、回應和參考 (Reference) schemas，使我們的設計更乾淨、更一致且更容易維護。

1. 什麼是可重複使用的元件？

元件 (Components) 是可以定義一次並在整個 API 中重複使用的構建區塊。元件的主要類型有：

Schemas (Models): 資料結構（從我們之前章節的 User 和 UserPreferences 就可以看到）。

Parameters: 重複使用的 URL 參數（例如查詢、header 或 cookie 參數）。

Responses: 標準回應（例如錯誤訊息或標準成功回應）。

Examples: 請求或回應的範例資料。

Security Schemes: 認證定義（我們將在下一章講到）。

透過使用元件，您可以：

確保一致性： 每個端點使用完全相同的錯誤格式。

節省時間： 定義一次，到處使用。

簡化維護： 更新一個元件，所有使用它的端點都會更新。

2. 建立可重複使用的參數

許多 API 端點使用相同的參數。例如，分頁參數 (page, limit) 或排序參數。

步驟 1：識別常見參數

對於我們的 User API，我們可能會在列出使用者的端點（未來的擴充）或日誌查詢中使用分頁。讓我們定義分頁參數。

page — 頁碼（整數，預設 1）

limit — 每頁項目數（整數，預設 20）

步驟 2：在 Apidog 中定義參數

在您的 Apidog 專案中，前往 Components 部分（通常在左側側邊欄底部或透過上方選單）。

選擇 Parameters。

點擊 ➕ New Parameter。

定義 page 參數：

Name: page

Located In: Query

Type: integer

Description: Page number required for pagination

Default: 1

重複步驟為 limit 參數：

Name: limit

Located In: Query

Type: integer

Default: 20

步驟 3：在端點中使用參數

一旦定義好，您可以將它們新增到任何端點：

前往端點編輯器（例如 GET /users，如果有的話）。

在 Request -> Parameters 部分。

點擊 "Reference Component" (引用元件) 連結圖示。

選擇 page 和 limit。

現在這些參數已連結。如果您更改元件中的描述或預設值，它會在所有使用它的端點中更新。

3. 建立標準錯誤回應 (Example: Generic Error)

錯誤回應在 API 中是非常重複的。大多數錯誤遵循相同的結構。讓我們為其建立一個元件。

步驟 1：定義錯誤 Schema

首先，我們需要一個錯誤的資料結構。

前往 Schemas。

建立新 schema "Error"。

使用 JSON 生成或手動新增欄位：

{
  "code": "INVALID_INPUT",
  "message": "The email address format is invalid.",
  "details": {
    "field": "email"
  }
}

code (string): 機器可讀的錯誤代碼。

message (string): 人類可讀的錯誤訊息。

details (object, optional): 錯誤的詳細資訊。

步驟 2：建立錯誤回應元件

現在建立實際的 HTTP 回應元件。

前往 Components -> Responses。

點擊 ➕ New Response。

命名為 "BadRequest" (或 "400 Error")。

設定：

Description: Invalid request parameters or body.

Content-Type: application/json (這是預設的，但確認一下)。

Schema: 選擇 "Error" schema。

(可選) 新增範例。

重複此過程建立 "NotFound" (404), "Unauthorized" (401), "InternalServerError" (500) 等，它們都使用相同的 Error schema，但可能有不同的描述或範例。

步驟 3：在端點中使用回應元件

將這些標準回應新增到您的端點：

前往 POST /users 或 GET /users/{id}。

在 Response 部分。

點擊 "Add Response"。

不要手動填寫，而是點擊 "Reference Component"。

選擇 "BadRequest", "NotFound", "Unauthorized" 等。

使用引用元件的回應將顯示為鏈接狀態。

4. 重用 Schemas (Schema Composition)

我們已經在「設計資料模型」一章中看過 Schema 引用 (User 引用 UserPreferences)。現在讓我們看看更進階的技術：Schema 組合 (Composition)。

這對於處理不同場景（如建立、更新、讀取）的變體非常有用，而不需要複製整個 schema。

場景：User vs UserUpdate

User (讀取): 包含 id, email, createdAt 等。

UserUpdate (更新): 僅包含可編輯欄位，且都是可選的。我們可以使用 allOf, oneOf, 或 Apidog 的繼承/克隆功能。

在 Apidog 中，最簡單的方法通常是直接在端點中引用基礎 schema 並調整可見性/必要性（如我們在上一章所做），但您也可以明確建立衍生 schema。

繼承/擴充 Schema:

建立新 schema "UserDetail"。

設定它繼承自 "User"。

新增額外欄位（如 lastLoginDate）。

這確保 UserDetail 始終擁有 User 的所有欄位，再加上額外的。

5. 管理您的元件庫

隨著專案增長，您的元件庫也會增長。保持其組織性很重要。

命名慣例

Schemas: 使用 PascalCase (e.g., User, UserProfile, ErrorResponse)。

Parameters: 使用 camelCase 或 snake_case，與實際參數名匹配 (e.g., userId, api_key)。

Responses: 使用描述性名稱或狀態碼 (e.g., NotFound, Standard404, SuccessCreated)。

分組

Apidog 允許您使用資料夾將元件分組。例如在 Schemas 下建立 Common, User, Product 資料夾。

6. 使用全局參數 (Global Parameters)

有些參數是每個請求都需要的，例如：

Authorization header (token)。

Accept-Language header。

您不必將它們新增到每個端點：

點擊專案設定或 Global Parameters (通常在介面某處，依版本而定)。

定義參數。

它們將自動應用於所有端點（或您可以配置特定的排除規則）。

注意：對於 Authorization，通常使用 Security parameters (安全方案)，我們將在下一章詳細介紹。

7. 關鍵收穫

使用元件是專業 API 設計的標誌：

不要重複自己 (DRY): 為重複使用的部分（schemas, parameters, responses）建立元件。

Schemas: 您的主要資料模型，應盡可能在請求和回應中引用。

Parameters: 定義標準查詢參數（如分頁、排序）。

Responses: 建立標準錯誤回應 (400, 401, 404, 500) 並在所有端點重複使用。

一致性: 元件確保您的 API 在所有端點上行為一致。

可維護性: 更改一個元件，更新整個 API。

現在您已經掌握了如何建立可重複使用的元件，您的 API 設計將更加穩健和易於管理。接下來，我們將解決 API 設計中最關鍵的部分之一：安全性。

讓我們繼續設定身分驗證。

使用組件與可重用性

1. 什麼是可重複使用的元件？#

2. 建立可重複使用的參數#

步驟 1：識別常見參數#

步驟 2：在 Apidog 中定義參數#

步驟 3：在端點中使用參數#

3. 建立標準錯誤回應 (Example: Generic Error)#

步驟 1：定義錯誤 Schema#

步驟 2：建立錯誤回應元件#

步驟 3：在端點中使用回應元件#

4. 重用 Schemas (Schema Composition)#

場景：User vs UserUpdate#

5. 管理您的元件庫#

命名慣例#

分組#

6. 使用全局參數 (Global Parameters)#

7. 關鍵收穫#