想像一下，你是建築師，站在空曠的土地上。你不會(huì)在沒有藍(lán)圖的情況下就開始砌磚，對(duì)吧？同樣的原則也適用於API開發(fā)。我過去使用程式碼優(yōu)先的方法，先編寫程式碼，然後在之後再編寫文檔，直到我學(xué)習(xí)了設(shè)計(jì)優(yōu)先的方法。設(shè)計(jì)優(yōu)先的方法是在編寫任何程式碼之前創(chuàng)建一個(gè)詳細(xì)的API定義。

本指南概述

在我們深入探討之前，讓我們先規(guī)劃一下我們的目標(biāo)?？梢园堰@當(dāng)成你的API規(guī)劃路線圖：

• 了解API規(guī)劃的基礎(chǔ)
• 探索兩種不同的方法
• 做出明智的選擇
• 建立你的API計(jì)畫

你將學(xué)到什麼：

1. API規(guī)劃包含什麼
2. 程式碼優(yōu)先方法
3. 設(shè)計(jì)優(yōu)先方法
4. 程式碼優(yōu)先與設(shè)計(jì)優(yōu)先的比較
5. 如何選擇正確的方法
6. API規(guī)劃的實(shí)際步驟

API規(guī)劃包含什麼

優(yōu)異API的基礎(chǔ)

API規(guī)劃不僅僅是關(guān)於技術(shù)規(guī)格——它也是關(guān)於建立其他人會(huì)喜歡使用的產(chǎn)品。這就像設(shè)計(jì)一棟房子，每個(gè)房間都有其用途，並與其他房間邏輯地連接起來。

需要回答的關(guān)鍵問題：

• 消費(fèi)者是誰？ （前端開發(fā)人員、第三方合作夥伴等）
• 它支援哪些操作？ （CRUD操作、整合等）
• 如何確保其安全性？ （身份驗(yàn)證、速率限制等）

規(guī)劃的藝術(shù)

將API規(guī)劃比喻為繪製傑作：

• 程式碼優(yōu)先就像不打草稿直接作畫
• 設(shè)計(jì)優(yōu)先就像先規(guī)劃好構(gòu)圖

程式碼優(yōu)先方法

程式碼優(yōu)先方法是指直接跳入編碼，在編寫API結(jié)構(gòu)文件或設(shè)計(jì)之前建立功能。當(dāng)我開始建立API時(shí)，我是一個(gè)程式碼優(yōu)先的擁護(hù)者。以下是我學(xué)到的：

<code>// 第一天：“這看起來很簡單！”
app.get('/users', getUsers);

// 第二周：“哦，等等，我需要過濾……”
app.get('/users', authenticateUser, validateQuery, getUsers);

// 第三周：“也許我應(yīng)該更好地規(guī)劃一下……”</code>

快速提示 ?：程式碼優(yōu)先適用於原型，但在進(jìn)行過程中要記錄你的決策！

工作原理

• 從後端開發(fā)和模型開始。
• 根據(jù)你的資料庫結(jié)構(gòu)建立API端點(diǎn)。
• 實(shí)作後編寫API文件。

優(yōu)點(diǎn)

• 更快的原型設(shè)計(jì)：非常適合小型團(tuán)隊(duì)或個(gè)人專案。
• 直接實(shí)作：專注於建置功能，無需前期規(guī)劃。

挑戰(zhàn)

• 設(shè)計(jì)不一致：如果涉及多位開發(fā)人員，API可能缺乏一致性。
• 迭代困難：開發(fā)後進(jìn)行重大變更可能代價(jià)高昂。

設(shè)計(jì)優(yōu)先方法

設(shè)計(jì)優(yōu)先方法強(qiáng)調(diào)在編寫任何程式碼之前規(guī)劃和定義API的結(jié)構(gòu)。它讓每個(gè)人都步調(diào)一致。在商定API定義後，利害關(guān)係人（例如測試人員和技術(shù)編寫者）可以與開發(fā)人員並行工作。

工作原理

• 使用Swagger/OpenAPI等工具設(shè)計(jì)API模式。
• 定義端點(diǎn)、請(qǐng)求/回應(yīng)格式和驗(yàn)證。
• 與利害關(guān)係人分享設(shè)計(jì)以獲得回饋。
• 在設(shè)計(jì)最終確定後開始開發(fā)。

優(yōu)點(diǎn)

• 協(xié)作：促進(jìn)利害關(guān)係人儘早回饋。
• 一致性：確保端點(diǎn)的一致性。
• 模擬API：允許前端團(tuán)隊(duì)使用模擬回應(yīng)更早開始整合。

挑戰(zhàn)

• 前期工作量：初始設(shè)計(jì)需要時(shí)間。
• 需要專業(yè)知識(shí)：開發(fā)人員必須熟悉設(shè)計(jì)工具和最佳實(shí)務(wù)。

程式碼優(yōu)先與設(shè)計(jì)優(yōu)先：比較

程式碼優(yōu)先

• 速度：對(duì)於簡單的項(xiàng)目更快。
• 協(xié)作：在初始階段有限。
• 一致性：這可能因端點(diǎn)而異。
• 靈活性：對(duì)於單獨(dú)開發(fā)很容易。
• 可擴(kuò)展性：這可能難以擴(kuò)展。

設(shè)計(jì)優(yōu)先

• 速度：因前期規(guī)劃而較慢。
• 協(xié)作：鼓勵(lì)早期團(tuán)隊(duì)協(xié)作。
• 一致性：確保標(biāo)準(zhǔn)化設(shè)計(jì)。
• 靈活性：非常適合團(tuán)隊(duì)或公開API。
• 可擴(kuò)展性：設(shè)計(jì)時(shí)考慮了可擴(kuò)展性。

如何選擇正確的方法

如果符合以下條件，請(qǐng)選擇代碼優(yōu)先：

• 你正在建立一個(gè)快速的概念驗(yàn)證或內(nèi)部API。
• API使用者是一個(gè)單一的小型團(tuán)隊(duì)。
• 你優(yōu)先考慮速度而不是設(shè)計(jì)。

如果符合以下條件，請(qǐng)選擇設(shè)計(jì)優(yōu)先：

• 你的API是針對(duì)外部使用者或多個(gè)團(tuán)隊(duì)。
• 協(xié)作和一致性是優(yōu)先事項(xiàng)。
• 你正在建立公用API或長期API。

API規(guī)劃的實(shí)際步驟

步驟1：定義API的目的

在深入研究端點(diǎn)和方法之前，請(qǐng)先回答以下基本問題：

• 你的API解決了什麼問題？
• 你的目標(biāo)用戶是誰？
• 你必須提供哪些核心功能？
• 你的非功能性需求是什麼？

範(fàn)例目的陳述：

<code>// 第一天：“這看起來很簡單！”
app.get('/users', getUsers);

// 第二周：“哦，等等，我需要過濾……”
app.get('/users', authenticateUser, validateQuery, getUsers);

// 第三周：“也許我應(yīng)該更好地規(guī)劃一下……”</code>

步驟2：辨識(shí)核心資源

將資源視為API中的名詞。對(duì)於我們的電子商務(wù)範(fàn)例：

主要資源：

• 產(chǎn)品
• 庫存
• 倉庫
• 庫存變動(dòng)

資源關(guān)係：

<code>// 第一天：“這看起來很簡單！”
app.get('/users', getUsers);

// 第二周：“哦，等等，我需要過濾……”
app.get('/users', authenticateUser, validateQuery, getUsers);

// 第三周：“也許我應(yīng)該更好地規(guī)劃一下……”</code>

步驟3：定義操作

現(xiàn)在考慮使用者需要對(duì)這些資源執(zhí)行哪些操作（動(dòng)詞）：

<code>此API使電子商務(wù)平臺(tái)能夠?qū)崟r(shí)管理多個(gè)倉庫的庫存，確保準(zhǔn)確的庫存水平并防止超賣。</code>

步驟4：規(guī)劃資料模型

定義清晰一致的資料結(jié)構(gòu)：

<code>產(chǎn)品
  └── 庫存
       └── 倉庫
            └── 庫存變動(dòng)</code>

步驟5：規(guī)劃驗(yàn)證與安全性

一開始就考慮安全性：

• 驗(yàn)證方法
• 授權(quán)等級(jí)
• 速率限制
• 資料加密
• 輸入驗(yàn)證

步驟6：寫API文件

建立全面的文件：

API概述

• 目的與範(fàn)圍
• 入門指南
• 身份驗(yàn)證詳細(xì)資訊

端點(diǎn)文件

• 資源描述
• 請(qǐng)求/回應(yīng)格式
• 範(fàn)例呼叫
• 錯(cuò)誤處理

用例

• 常用場景
• 整合範(fàn)例
• 最佳實(shí)踐

結(jié)論

程式碼優(yōu)先和設(shè)計(jì)優(yōu)先方法在API開發(fā)中都很有價(jià)值。關(guān)鍵在於選擇符合專案需求、團(tuán)隊(duì)規(guī)模和長期目標(biāo)的方法。最終，無論你選擇程式碼優(yōu)先還是設(shè)計(jì)優(yōu)先方法，目標(biāo)都是創(chuàng)建一個(gè)開發(fā)人員喜歡使用的API。有時(shí)，旅程不如目的地重要，但擁有一張好的地圖可以讓旅程更容易！

展望：CollabSphere案例研究

在我們即將推出的部落格系列中，我們將透過建立CollabSphere（一個(gè)即時(shí)聊天系統(tǒng)）將這些原則付諸實(shí)踐。你將親眼目睹我如何將程式碼優(yōu)先專案轉(zhuǎn)變?yōu)樵O(shè)計(jì)優(yōu)先傑作。

即將推出的內(nèi)容預(yù)覽：

• 從頭設(shè)計(jì)聊天API
• 建立全面的API文件
• 實(shí)現(xiàn)即時(shí)功能
• 處理身份驗(yàn)證和安全性

以上是API 規(guī)劃指南：程式碼優(yōu)先 VS 設(shè)計(jì)優(yōu)先方法的詳細(xì)內(nèi)容。更多資訊請(qǐng)關(guān)注PHP中文網(wǎng)其他相關(guān)文章！