分析需求並規劃您的 API

既然您已經在 Apidog 中設定好了您的 API 專案，是時候開始設計流程了。在您開始設計端點或建立 schema 之前，您需要了解您的 API 應該做什麼以及誰將使用它。這看起來可能很明顯，但跳過這一步驟是 API 設計中最常見的錯誤之一。

需求分析是良好 API 設計的基礎。如果沒有明確的需求，您可能會建立沒人需要的端點，遺漏關鍵功能，或者建立一個令人困惑的 API。

在本章中，我們將學習如何分析需求並規劃您的 API 結構。我們將全程使用 Pet Store User 模組作為範例，逐步完成從需求到規劃 API 結構的完整過程。

1. 為什麼需求分析很重要

想像一下在沒有藍圖的情況下建造房屋，或在沒有食譜的情況下做飯。您可能會得到一些東西，但它可能不是您真正需要的。

API 也是如此。需求分析幫助您：

了解您正在解決的問題

識別實際需要什麼功能

避免建立不必要的端點

設計使用者真正會使用的 API

透過第一次就做對來節省時間

如果沒有需求分析會發生什麼？

如果沒有適當的需求分析，您可能會：

❌ 建立不符合使用者需求的端點

❌ 遺漏重要功能（如身分驗證或驗證）

❌ 設計不一致或令人困惑的 API

❌ 稍後浪費時間重新設計

❌ 建立沒人使用的功能

範例： 如果您在不了解使用者需要登入的情況下開始設計 User API，您可能會忘記包含身分驗證端點。然後您稍後將不得不重新設計所有內容。

2. 如何收集和分析需求

需求分析是一個系統化的過程。讓我們將其分解為幾個步驟：

步驟 1：識別商業目標

首先了解為什麼您要建立這個 API。它解決了什麼問題？

Pet Store User 模組的範例：

目標： 允許客戶建立帳戶並管理他們的資訊

問題： 客戶需要一種保存偏好、查看訂單記錄和維護個人資料的方法

價值： 更好的客戶體驗、個人化服務、訂單追蹤

步驟 2：確定 API 使用案例

思考 API 將如何被使用。具體場景是什麼？

User API 的範例使用案例：

新客戶註冊： 新使用者想要建立帳戶

使用者登入： 現有使用者想要登入以存取他們的帳戶

查看個人資料： 已登入的使用者想要查看他們的帳戶資訊

更新個人資料： 使用者想要更改他們的電子郵件或電話號碼

管理偏好： 使用者想要更新他們的電子報偏好

帳戶刪除： 使用者想要刪除他們的帳戶

步驟 3：識別使用者角色和權限

誰將使用您的 API，他們能做什麼？

對於 Pet Store User API：

公開使用者（未登入）：

可以建立新帳戶

可以登入

已驗證使用者：

可以查看自己的個人資料

可以更新自己的個人資料

可以管理他們的偏好

可以登出

可以刪除自己的帳戶

系統/管理員（未來考量）：

可能需要查看所有使用者（不在初始範圍內）

步驟 4：了解資料流和商業規則

資料如何在您的系統中移動？規則是什麼？

對於 User API：

當使用者註冊時，他們必須提供電子郵件、名字和姓氏

電子郵件必須是唯一的（不能有重複帳戶）

密碼絕不應在 API 回應中返回

使用者只能存取他們自己的資料

使用者偏好是可選的，並有預設值

3. 識別核心資源

一旦您了解了需求，下一步就是識別資源——您的 API 將管理的主要實體。

什麼是資源？

資源是您的 API 管理的事物。在 REST API 中，資源通常是：

名詞（不是動詞）

您可以建立、讀取、更新或刪除的事物

具有屬性的事物

資源範例：

Users (使用者)

Orders (訂單)

Products (產品)

Pets (寵物)

Categories (類別)

如何從需求中提取資源

查看您的使用案例並識別正在管理的主要「事物」：

從我們的 User API 使用案例：

✅ User — 主要資源（使用者建立帳戶、查看個人資料等）

❌ "Login" — 這是一個動作，不是資源

❌ "Registration" — 這是一個動作，不是資源

等等，那登入呢？ 登入是對 User 資源的操作，而不是資源本身。我們將其作為特殊端點處理。

資源關係

資源通常彼此相關。了解這些關係有助於您設計更好的 API。

對於 Pet Store（User 模組之外）：

一個 User 可以有許多 Orders（一對多）

一個 Order 屬於一個 User（多對一）

一個 Pet 可以有許多 Tags（多對多）

對於 User 模組（目前範圍）：

一個 User 有一組 Preferences（一對一）

這是一個巢狀物件，不是分開的資源

4. 確定所需的操作

既然您知道了資源，請確定可以對它們執行什麼操作（動作）。

標準 CRUD 操作

對於大多數資源，您需要 CRUD 操作：

操作	HTTP 方法	目的	範例
Create	POST	新增資源	建立新使用者
Read	GET	檢索資源	獲取使用者資訊
Update	PUT/PATCH	修改資源	更新使用者個人資料
Delete	DELETE	移除資源	刪除使用者帳戶

特殊操作

除了 CRUD 之外，您可能需要特殊操作：

對於 User API：

Login — 驗證並獲取 token

Logout — 使 session token 無效

這些不符合標準 CRUD 模式，因此它們有自己的端點。

User 資源的操作

基於我們的需求分析：

操作	HTTP 方法	端點	描述
Create User	POST	`/users`	註冊新使用者帳戶
Get User	GET	`/users/{id}`	檢索使用者資訊
Update User	PUT	`/users/{id}`	更新使用者個人資料
Delete User	DELETE	`/users/{id}`	刪除使用者帳戶
Login	POST	`/user/login`	驗證並獲取 token
Logout	POST	`/user/logout`	使 session token 無效

注意： 請注意，login/logout 使用 /user（單數）而不是 /users（複數）。這是對於不操作特定資源實例的操作的常見慣例。

5. 規劃端點結構

現在讓我們將您的資源和操作映射到實際的端點 (URL)。

從資源和操作到端點

映射很直觀：

資源: User
操作:
  - Create → POST /users
  - Read → GET /users/{id}
  - Update → PUT /users/{id}
  - Delete → DELETE /users/{id}
  - Login → POST /user/login (特殊操作)
  - Logout → POST /user/logout (特殊操作)

RESTful 路徑設計原則

在設計路徑時，請遵循以下原則：

對集合使用複數名詞：

✅ /users (users 的集合)

❌ /user (除非是特殊操作)

對特定資源使用路徑參數：

✅ /users/{id} (特定使用者)

❌ /users/getById?id=123 (使用查詢參數進行過濾，而不是識別)

保持路徑階層化：

✅ /users/{id}/orders (使用者的訂單)

❌ /userOrders?userId=123 (較不 RESTful)

使用一致的命名：

✅ /users/{id}

❌ /users/{userId} (多餘 - 我們知道它是使用者 ID)

User 模組的完整端點列表

這是我們完整的端點計畫：

POST   /users           - Create a new user
GET    /users/{id}      - Get user by ID
PUT    /users/{id}      - Update user
DELETE /users/{id}      - Delete user
POST   /user/login      - User login
POST   /user/logout     - User logout

端點分組和組織

在 Apidog 中，您可以使用以下方式組織端點：

資料夾 — 將相關端點分組

標籤 (Tags) — 對端點進行分類（例如 "User", "Authentication"）

模組 — 分開不同的功能區域

對於 User 模組，我們可以這樣組織：

User Module/
  ├── User Management/
  │   ├── POST /users
  │   ├── GET /users/{id}
  │   ├── PUT /users/{id}
  │   └── DELETE /users/{id}
  └── Authentication/
      ├── POST /user/login
      └── POST /user/logout

6. 識別資料需求

最後，確定每個資源需要什麼資料。哪些欄位是必需的？哪些是可選的？

User 資源的資料需求

基於我們的使用案例，User 需要：

必需欄位：

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

email — 用於登入和通訊（必須唯一）

firstName — 使用者的名字

lastName — 使用者的姓氏

createdAt — 帳戶建立時間（由系統生成）

可選欄位：

phone — 電話號碼（用於聯絡）

preferences — 使用者偏好物件

newsletter — 是否接收電子報 (boolean)

notifications — 是否接收通知 (boolean)

身分驗證欄位：

password — 用於登入（絕不返回，唯寫）

欄位關係

某些欄位彼此相關：

preferences 是 User 內的巢狀物件（不是分開的資源）

id 和 createdAt 是唯讀（由系統設定）

password 是唯寫（絕不返回）

資料驗證需求

每個欄位都需要驗證規則：

欄位	類型	驗證規則
`id`	string	模式: `usr_[A-Za-z0-9]{16}`, 唯讀
`email`	string	有效的 email 格式, 唯一, 必需
`firstName`	string	必需, 最多 50 個字元
`lastName`	string	必需, 最多 50 個字元
`phone`	string	可選, 如果提供需為 E.164 格式
`password`	string	建立時必需, 唯寫, 至少 8 個字元
`preferences.newsletter`	boolean	可選, 預設: false
`preferences.notifications`	boolean	可選, 預設: true
`createdAt`	date-time	唯讀, ISO 8601 格式

7. 整合所有內容：User API 計畫

讓我們總結我們規劃的所有內容：

資源

User — 主要資源

端點

POST   /users           - Create user
GET    /users/{id}      - Get user
PUT    /users/{id}      - Update user
DELETE /users/{id}      - Delete user
POST   /user/login      - Login
POST   /user/logout     - Logout

資料模型（摘要）

User 物件包含：

必需：id, email, firstName, lastName, createdAt

可選：phone, preferences

身分驗證：password (唯寫)

身分驗證

Token 需要用於：GET, PUT, DELETE /users/{id}, 以及 logout

Create 和 login 端點是公開的

8. 關鍵收穫

在開始設計之前，需求分析和規劃至關重要：

需求分析確保您建立實際需要的東西

使用案例幫助您了解 API 將如何被使用

資源是您的 API 管理的主要實體（名詞）

操作是對資源執行的動作（CRUD + 特殊操作）

端點將資源和操作映射到 URL

資料需求定義每個資源需要什麼欄位

規劃節省時間，因為從一開始就做對了結構

既然您有了 User API 的明確計畫，您準備好設計詳細的資料模型並在 Apidog 中將它們作為 schema 實作。在下一章中，我們將學習如何設計和實作您的資料模型——建立具有確切結構、類型和驗證規則的 schemas。

讓我們繼續設計和實作資料模型。

分析需求並規劃您的 API

1. 為什麼需求分析很重要#

如果沒有需求分析會發生什麼？#

2. 如何收集和分析需求#

步驟 1：識別商業目標#

步驟 2：確定 API 使用案例#

步驟 3：識別使用者角色和權限#

步驟 4：了解資料流和商業規則#

3. 識別核心資源#

什麼是資源？#

如何從需求中提取資源#

資源關係#

4. 確定所需的操作#

標準 CRUD 操作#

特殊操作#

User 資源的操作#

5. 規劃端點結構#

從資源和操作到端點#

RESTful 路徑設計原則#

User 模組的完整端點列表#

端點分組和組織#

6. 識別資料需求#

User 資源的資料需求#

欄位關係#

資料驗證需求#

7. 整合所有內容：User API 計畫#

資源#

端點#

資料模型（摘要）#

身分驗證#

8. 關鍵收穫#