設計資料模型

在上一章中，您確定了您的 API 需要什麼資料。現在是時候設計資料模型並在 Apidog 中將其作為 schemas 實作了。

資料模型定義了您 API 資料的結構——存在什麼欄位、它們的類型、驗證規則以及如何使用它們。Schemas 是這些模型在 Apidog 中使用 JSON Schema 的技術實作。

在本章中，我們將學習如何設計資料模型並立即將它們作為 Apidog 中的 schemas 實作。我們將使用 Pet Store User 模組作為範例，逐步建立 schemas。

1. 什麼是資料模型和 Schemas？

資料模型是資料結構的概念設計。Schema 是實作該模型的技術規格。

可以這樣想：

資料模型 = 藍圖（您設計的）

Schema = Apidog/OpenAPI 中的實際規格（您實作的）

在 Apidog 中，schemas 基於 JSON Schema 並定義：

欄位名稱和類型

必需 vs 可選欄位

驗證規則（格式、長度、模式）

巢狀物件和陣列

預設值

2. 設計流程

在設計資料模型時，請遵循此方法：

從需求開始 — 您需要什麼資料？（來自上一章）

設計模型 — 什麼欄位、類型和規則？

作為 schema 實作 — 在 Apidog 中建立它

測試和完善 — 驗證設計

讓我們將其應用於 User 模組。

3. 設計 User 模型

基於我們的需求分析，User 需要：

必需欄位：

id — 唯一識別碼（由系統生成）

email — 用於登入和通訊

firstName — 使用者的名字

lastName — 使用者的姓氏

createdAt — 帳戶建立時間戳記

可選欄位：

phone — 電話號碼

preferences — 使用者偏好（巢狀物件）

身分驗證：

password — 用於登入（絕不返回在回應中）

User 模型結構

User 模型看起來像這樣：

{
  "id": "usr_3Oy2JIS7TMJgEXfM",
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+14155551234",
  "preferences": {
    "newsletter": true,
    "notifications": false
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

4. 在 Apidog 中建立 Schemas

現在讓我們在 Apidog 中將此模型作為 schema 實作。Apidog 推薦的方法是直接貼上 JSON，它將自動識別並生成 schema 結構。

步驟 1：建立 User Schema

在您的 Apidog 專案中，前往 Schemas 部分

點擊 ➕ 圖示並選擇 New Schema

將其命名為 "User" 並新增描述："User account information"

步驟 2：從 JSON 生成 Schema

Apidog 允許您貼上 JSON 並自動生成 schema，而不是手動逐一新增屬性：

點擊 Schema 編輯器中的 「Generate from JSON etc.」 按鈕

貼上以下 JSON：

{
  "id": "usr_3Oy2JIS7TMJgEXfM",
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+14155551234",
  "preferences": {
    "newsletter": true,
    "notifications": false
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Apidog 將自動：

識別所有屬性及其類型

設定適當的資料類型 (string, boolean, object, date-time)

建立巢狀的 preferences 物件結構

注意： 預設情況下，JSON 中的所有屬性都將標記為 required。您需要手動調整可選欄位。

步驟 3：完善生成的 Schema

從 JSON 生成後，完善 schema：

將可選欄位標記為非必需：

取消勾選 phone 和 preferences 的 "Required"

新增驗證規則：

id：新增模式 ^usr_[A-Za-z0-9]{16}$ 並標記為唯讀 (read-only)

email：設定格式為 email，新增最大長度 255

firstName 和 lastName：新增最大長度 50

phone：新增模式 ^\+?[1-9]\d{1,14}$ (E.164 格式)

createdAt：設定格式為 date-time 並標記為唯讀

新增描述到每個欄位以獲得更好的文件說明

提示： Apidog 的 JSON 智慧識別會根據 JSON 值生成資料結構，但不會保存實際值。您可以隨後新增描述並調整驗證規則。

5. 建立巢狀 Schemas：UserPreferences

preferences 欄位是一個巢狀物件。讓我們為它建立一個單獨的 schema，以便我們可以重複使用它。

步驟 1：建立 UserPreferences Schema

建立一個名為 "UserPreferences" 的新 schema

新增描述："User communication preferences"

步驟 2：從 JSON 生成

點擊 「Generate from JSON etc.」

貼上此 JSON：

{
  "newsletter": true,
  "notifications": false
}

Apidog 將自動識別兩個 boolean 欄位

步驟 3：完善 Schema

將兩個欄位標記為可選（取消勾選 "Required"）

設定預設值：

newsletter：預設 false

notifications：預設 true

新增描述到每個欄位

步驟 4：在 User Schema 中引用

現在回到 User schema 並：

選擇 preferences 屬性

將其類型更改為 Reference

從清單中選擇 UserPreferences

這建立了一個引用，允許您重複使用 UserPreferences schema。如果您稍後更新 UserPreferences，所有引用都會自動反映這些更改。

6. Schema 最佳實踐

在設計 schemas 時，請記住這些原則：

保持簡單 (Keep It Simple)

避免過度設計： 不要新增「以防萬一」的欄位

儘可能使用簡單類型： 適當時優先選擇 string 而不是複雜物件

將相關欄位分組： 使用巢狀物件進行邏輯分組（如 preferences）

避免過度巢狀 (Avoid Over-Nesting)

盡量將巢狀保持在最多 2-3 層。深度巢狀使 schemas 難以理解和使用。

使用 Schema 引用

當您有可重複使用的結構（如 UserPreferences）時，建立單獨的 schemas 並引用它們。這：

減少重複

使更新更容易

提高一致性

安全考量

絕不在回應 schemas 中包含密碼

使用唯寫 (write-only) 用於敏感輸入欄位 (password)

使用唯讀 (read-only) 用於系統生成的欄位 (id, createdAt)

根據您的規則驗證所有輸入

為可擴展性規劃

使用可選欄位用於新功能

避免移除欄位（改為標記為棄用）

使用 API 版本控制用於重大變更

7. 關鍵收穫

設計和實作資料模型是關鍵步驟：

資料模型定義您的 API 使用什麼資料

Schemas 是 Apidog 中的技術實作

使用「Generate from JSON」 以從 JSON 資料快速建立 schemas

使用 schema 引用用於可重複使用的結構（如 UserPreferences）

首先建立核心 schemas — 請求/回應變體可以在端點層級處理

安全很重要： 使用唯寫用於敏感欄位，唯讀用於系統生成欄位

保持簡單： 避免過度巢狀和過度設計

既然您已經設計並實作了核心 schemas，您準備好開始建構端點了。在下一章中，我們將學習如何在 Apidog 中設計端點，使用我們建立的 schemas 和我們之前規劃的端點結構。

讓我們繼續設計端點。

1. 什麼是資料模型和 Schemas？#

2. 設計流程#

3. 設計 User 模型#

User 模型結構#

4. 在 Apidog 中建立 Schemas#

步驟 1：建立 User Schema#

步驟 2：從 JSON 生成 Schema#

步驟 3：完善生成的 Schema#

5. 建立巢狀 Schemas：UserPreferences#

步驟 1：建立 UserPreferences Schema#

步驟 2：從 JSON 生成#

步驟 3：完善 Schema#

步驟 4：在 User Schema 中引用#

6. Schema 最佳實踐#

保持簡單 (Keep It Simple)#

避免過度巢狀 (Avoid Over-Nesting)#

使用 Schema 引用#

安全考量#

為可擴展性規劃#

7. 關鍵收穫#