一杯咖啡的時(shí)間??，搞懂 API 和 RESTful API！

時(shí)間：2023-08-25 03:48:01 | 來源：網(wǎng)站運(yùn)營

時(shí)間：2023-08-25 03:48:01 來源：網(wǎng)站運(yùn)營

• API和RESTful API 是每個(gè)程序員都應(yīng)該了解并掌握的基本知識(shí)，我們?cè)陂_發(fā)過程中設(shè)計(jì) API 的時(shí)候也應(yīng)該至少要滿足一些最基本的要求。
• 如果你還不了解什么是API或你沒有了解RESTful API，你可以選擇花5分鐘時(shí)間看下去，我會(huì)最通俗易懂的幫你普及這一切。

? 什么是 API

• 舉個(gè)簡(jiǎn)單的例子你就會(huì)明白：
• 早在2000年我們還在用小靈通的時(shí)代，網(wǎng)上購票已經(jīng)慢慢興起，但是絕大部分人出行還是「通過電話查詢航班來去選擇購票」，我們首先需要「打電話」到附近的站臺(tái)根據(jù)時(shí)間「詢問」航班或車次，得到結(jié)果后再去到對(duì)應(yīng)站臺(tái)進(jìn)行購票。

• 隨著時(shí)代的飛速發(fā)展和智能手機(jī)的普及，各種旅游App也映入眼簾，大家也「學(xué)會(huì)了如何在App上進(jìn)行購票」。
• 這時(shí)候我們買票就沒有以前那么麻煩了，在App輸入你的「起點(diǎn)」和「終點(diǎn)」后，會(huì)展現(xiàn)所有符合條件的車次，航班，不僅僅只有時(shí)間、座位，還有航空公司、預(yù)計(jì)時(shí)間等等等等詳細(xì)信息「一目了然」，你只需要根據(jù)你的需求購買即可。

• 連接是一件很棒的事情，在我們現(xiàn)在的生活中，我們可以很輕松的通過App進(jìn)行購物、閱讀、直播，我們以前所未有的方式和世界與人們相連接。
• 那這些是怎么做到的？為什么一個(gè)App能夠這么便利？這些資料為什么會(huì)可以從A到達(dá)B，為什么我們只需要?jiǎng)觿?dòng)手指就可以達(dá)到這一切？
• 而這個(gè)橋梁，這個(gè)互聯(lián)網(wǎng)世界的無名英雄就是API，API，全名 Application Programming Interface (應(yīng)用程式界面)，簡(jiǎn)單來說，是品牌開發(fā)的一種接口，讓第三方可以額外開發(fā)、應(yīng)用在自身的產(chǎn)品上的系統(tǒng)溝通界面。
• 簡(jiǎn)單來說，你可以把它比喻成古人的鴿子，通過飛鴿傳書來傳達(dá)你的需求，而接收方再把回應(yīng)通過鴿子傳達(dá)給你。
• 再說回上面舉的例子。
• 舊時(shí)代我們需要知道航班的信息，我們就需要一個(gè)「信差」，而這個(gè)電話員就是這個(gè)信差，也就是我們說的 API，他傳達(dá)你的要求到系統(tǒng)，而站臺(tái)就是這個(gè)系統(tǒng)，比如告訴它查詢明天飛往杭州的飛機(jī)，那么他就會(huì)得出結(jié)果，由電話員傳遞給你。
• 而現(xiàn)在我們需要購買機(jī)票等，只需要通過購票系統(tǒng)選擇日期，城市，艙位等，他會(huì)從不同的航空公司網(wǎng)站匯集資料，而匯集資料的手段就是通過API和航空公司互動(dòng)。
• 我們現(xiàn)在知道是API讓我們使用這些旅游 App，那么這個(gè)道理也一樣適用于生活中任何應(yīng)用程序、資料和裝置之間的互動(dòng)，都有各自的API進(jìn)行連接。

? 什么是 RESTful API

• 在互聯(lián)網(wǎng)并沒有完全流行的初期，移動(dòng)端也沒有那么盛行，頁面請(qǐng)求和并發(fā)量也不高，那時(shí)候人們對(duì)接口（API）的要求沒那么高。
• 當(dāng)初的 web 應(yīng)用程序主要是在服務(wù)器端實(shí)現(xiàn)的，因此需要使用復(fù)雜的協(xié)議來操作和傳輸數(shù)據(jù)。然而，隨著移動(dòng)端設(shè)備的普及，需要在移動(dòng)端也能夠訪問 web 應(yīng)用程序，而客戶端和服務(wù)端就需要接口進(jìn)行通信，但接口的規(guī)范性就又成了一個(gè)問題。

• 所以一套「簡(jiǎn)化開發(fā)、結(jié)構(gòu)清晰、符合標(biāo)準(zhǔn)、易于理解、易于擴(kuò)展」讓大部分人都能夠理解接受的接口風(fēng)格就顯得越來越重要，而RESTful風(fēng)格的接口(RESTful API)剛好有以上特點(diǎn)，就逐漸應(yīng)運(yùn)而生。

REST

• REST，全名 Representational State Transfer(表現(xiàn)層狀態(tài)轉(zhuǎn)移)，他是一種「設(shè)計(jì)風(fēng)格」，一種「軟件架構(gòu)風(fēng)格」，而「不是標(biāo)準(zhǔn)」，只是「提供了一組設(shè)計(jì)原則和約束條件」。

RESTful

• RESTful 只是轉(zhuǎn)為形容詞，就像那么 RESTful API 就是滿足 REST 風(fēng)格的，以此規(guī)范設(shè)計(jì)的 API。

RESTful API

• 我們常見的 API 一般都長(zhǎng)這樣子：

• 而 RESTful 風(fēng)格的 API 卻長(zhǎng)這樣子：

六大原則

• Roy Fielding 是 HTTP 協(xié)議的主要設(shè)計(jì)者之一，他在論文中闡述了 REST 架構(gòu)的概念并給出了 REST 架構(gòu)的「六個(gè)限制條件」，也就是「六大原則」。

Uniform Interface（統(tǒng)一接口）

• 就像我們上面兩幅圖看到的 API，這是最直觀的特征，是 REST 架構(gòu)的核心，統(tǒng)一的接口對(duì)于 RESTful 服務(wù)非常重要?？蛻舳?b>「只需要關(guān)注實(shí)現(xiàn)接口」就可以，接口的「可讀性加強(qiáng)」，使用人員「方便調(diào)用」。
• RESTful API 通過 URL 定位資源，并通過 HTTP 方法操作該資源，對(duì)資源的操作包括獲取、創(chuàng)建、修改和刪除，這些操作正好對(duì)應(yīng) HTTP 協(xié)議提供的GET、POST、PUT和DELETE方法。
• GET：獲取資源信息。
• POST：創(chuàng)建一個(gè)新資源。
• PUT：更新已有的資源。
• DELETE：刪除已有的資源。
• 在一個(gè)完全遵循 RESTful 的團(tuán)隊(duì)里，后端只需要告訴前端 /users 這個(gè) API，前端就應(yīng)該知道:
• 獲取所有用戶：GET /users
• 獲取特定用戶：GET /users/{id}
• 創(chuàng)建用戶：POST /users
• 更新用戶：PUT /users/{id}
• 刪除用戶：DELETE /users/{id}
• 當(dāng) API 數(shù)量非常多，系統(tǒng)非常復(fù)雜時(shí)，RESTful 的好處會(huì)越來越明顯。理解系統(tǒng)時(shí)，可以直接圍繞一系列資源來理解和記憶。

Client-Server（客戶端和服務(wù)端分離）

• 它意味著客戶端和服務(wù)器是「獨(dú)立的」、可以「分離的」。
• 客戶端是負(fù)責(zé)請(qǐng)求和處理數(shù)據(jù)的組件，服務(wù)器是負(fù)責(zé)「存儲(chǔ)數(shù)據(jù)」和「處理請(qǐng)求」的組件。
• 這兩個(gè)組件之間「通過一組約定來協(xié)作」，以便客戶端能夠獲取所需的數(shù)據(jù)。

Statelessness（無狀態(tài)）

• 它指的是每個(gè)請(qǐng)求都是「獨(dú)立的」，「沒有前后關(guān)系」。服務(wù)器不保存客戶端的狀態(tài)信息，并且每個(gè)請(qǐng)求都必須包含所有所需的信息。
• 這樣做的好處是可以使每個(gè)請(qǐng)求變得「簡(jiǎn)單」，「容易理解」和「處理」，并且可以「更容易地?cái)U(kuò)展和維護(hù)」。
• 例如，假設(shè)你在登錄一個(gè)網(wǎng)站，你需要在登錄界面輸入用戶名和密碼通過接口獲取到了 token 。接下來的所有請(qǐng)求都需要攜帶上這個(gè) token 而不是系統(tǒng)在第一次登錄成功之后記錄了你的狀態(tài)。

Cacheability（可緩存）

• 客戶端和服務(wù)端可以協(xié)商緩存內(nèi)容，通過設(shè)置 HTTP 狀態(tài)碼，服務(wù)器可以告訴客戶端這個(gè)數(shù)據(jù)是否可以被緩存。
• 例如，一個(gè) HTTP 響應(yīng)頭中包含一個(gè) Cache-Control 字段，用于告訴客戶端該數(shù)據(jù)可以緩存多長(zhǎng)時(shí)間。這樣可以提高數(shù)據(jù)傳輸?shù)男?，從而降低網(wǎng)絡(luò)帶寬的開銷，加速數(shù)據(jù)的訪問速度。

Layered System（分層）

• 客戶端不應(yīng)該關(guān)心請(qǐng)求經(jīng)過了多少中間層，只需要關(guān)心請(qǐng)求的結(jié)果。
• 架構(gòu)的系統(tǒng)可以分為多個(gè)層次，每一層獨(dú)立完成自己的任務(wù)。這樣的架構(gòu)結(jié)構(gòu)使得系統(tǒng)更容易維護(hù)，并且允許獨(dú)立替換不同層次。
• 例如，數(shù)據(jù)庫存儲(chǔ)層可以獨(dú)立于其他層，在不影響其他層的情況下進(jìn)行替換或擴(kuò)展。

Code on Demand（可選的代碼請(qǐng)求）

• 它提倡服務(wù)器可以將客戶端代碼下載到客戶端并執(zhí)行。這樣，客戶端可以根據(jù)服務(wù)器發(fā)送的代碼來擴(kuò)展它的功能。
• 這個(gè)限制可以使客戶端代碼變得更加靈活，并且可以通過服務(wù)器提供的代碼來解決問題，而不必再等待下一個(gè)版本。
• Code on Demand 是可選的，但它可以使 RESTful API 變得更加靈活和可擴(kuò)展。

?? RESTful API 設(shè)計(jì)規(guī)范

• 說了這么多的理論，那我們?cè)撊绾稳ピO(shè)計(jì)一個(gè)最簡(jiǎn)單 RESTful 風(fēng)格的 API 呢？

HTTP 方法

• HTTP 設(shè)計(jì)了很多動(dòng)詞，來標(biāo)識(shí)不同的操作，不同的HTTP請(qǐng)求方法有各自的含義，就像上面所展示的，RESTful API 應(yīng)該使用 HTTP 方法（如 GET、POST、PUT 和 DELETE）來描述操作。

版本控制

• 版本控制是指在不影響現(xiàn)有的客戶端應(yīng)用的情況下，更新 RESTful API 的方法，據(jù)我了解常見的版本控制方式包括：
• 「URL 方法」：通過改變 URL 來表示不同的版本，例如 https://api.example.com/api/v1/resources 和 https://api.example.com/api/v2/resources。
• 「Accept 標(biāo)頭」：通過請(qǐng)求標(biāo)頭中的 Accept 字段來表示版本。
• 「請(qǐng)求參數(shù)」：通過請(qǐng)求中的參數(shù)來表示版本，例如 https://api.example.com/resources?version=1 和 https://api.example.com/resources?version=2。


• 不同公司，不同的團(tuán)隊(duì)所設(shè)計(jì)的 API 都各有不同，但我覺得 RESTful API 版本控制的方法要盡可能的簡(jiǎn)單，易于理解和使用直接將版本放到 URL 中，直截了當(dāng)，簡(jiǎn)單明了。

URL 明確標(biāo)識(shí)資源

• API 應(yīng)該使用簡(jiǎn)潔明了的 URL 來標(biāo)識(shí)資源，并且在同一個(gè)資源上使用不同的 HTTP 方法來執(zhí)行不同的操作。
• 這樣的設(shè)計(jì)使得客戶端在無需任何額外信息的情況下就可以找到所需的資源。
• 不規(guī)范的的 URL，形式千奇百怪，不同的開發(fā)者還需要了解文檔才能調(diào)用。
• 規(guī)范后的 RESTful 風(fēng)格的 URL，形式固定，可讀性強(qiáng)，根據(jù)名詞和 HTTP 動(dòng)詞就可以操作這些資源。

• 給大家一個(gè)小 tips，如果你遇到了實(shí)在想不到的 URL ，你可以參考github開放平臺(tái) [1]，這里面有很多很規(guī)范的 URL 設(shè)計(jì)。

HTTP 狀態(tài)碼

• HTTP 狀態(tài)碼是 RESTful API 設(shè)計(jì)的重要一環(huán)，是表示 API 請(qǐng)求的狀態(tài)，用于告知客戶端是否成功請(qǐng)求并處理數(shù)據(jù)。常用的 HTTP 狀態(tài)碼有：
• 200 OK：請(qǐng)求成功，表示獲得了請(qǐng)求的數(shù)據(jù)
• 201 Created：請(qǐng)求成功，表示創(chuàng)建了一個(gè)新的資源
• 204 No Content：請(qǐng)求成功，表示操作成功，但沒有返回?cái)?shù)據(jù)
• 400 Bad Request：請(qǐng)求失敗，表示請(qǐng)求格式不正確或缺少必要參數(shù)
• 401 Unauthorized：請(qǐng)求失敗，表示認(rèn)證失敗或缺少授權(quán)
• 403 Forbidden：請(qǐng)求失敗，表示沒有訪問權(quán)限
• 404 Not Found：請(qǐng)求失敗，表示請(qǐng)求的資源不存在
• 500 Internal Server Error：請(qǐng)求失敗，表示服務(wù)器內(nèi)部錯(cuò)誤

統(tǒng)一返回?cái)?shù)據(jù)格式

• 常用的返回?cái)?shù)據(jù)格式有 JSON 和 XML。
• JSON 是現(xiàn)在比較流行的數(shù)據(jù)格式，它是簡(jiǎn)單、輕量、易于解析，并且它有很好的可讀性。
• XML 也是一種常用的數(shù)據(jù)格式，它的優(yōu)點(diǎn)是比較靈活，并且支持各種數(shù)據(jù)類型。

合格美觀的 API 文檔

• 項(xiàng)目開發(fā)離不開前后端分離，離不開 API，當(dāng)然也就離不開 API 文檔，但是文檔的編寫又成為程序員覺得麻煩事之一，甚至我還看到有公司的的 API 文檔是用 Word 文檔手敲的。
• 市面上有很多可以管理 API 的軟件，每個(gè)人都有自己的選擇，我給大家推薦一款 API 管理神器 Apifox[2]，可以一鍵生成 API 文檔。
• 不需要你過多的操作，只需要你在可視化的頁面添加你的 API 即可生成，現(xiàn)在也支持了「多種導(dǎo)航模式」、「亮暗色模式」、「頂部自定義 Icon 、文案可跳轉(zhuǎn)到你的官網(wǎng)等地址」。

• 對(duì)于獨(dú)立開發(fā)者和團(tuán)隊(duì)來說都是一大利好福音，本文就不做過多介紹，感興趣的可以去試試～

寫在最后

• 總的來說 RESTful 風(fēng)格的 API 固然很好很規(guī)范，但大多數(shù)互聯(lián)網(wǎng)公司并沒有按照或者完全按照其規(guī)則來設(shè)計(jì)，因?yàn)?REST 是一種風(fēng)格，而不是一種約束或規(guī)則，過于理想的 RESTful API 會(huì)付出太多的成本。
• 如果您正在考慮使用 RESTful API，請(qǐng)確保它符合您的業(yè)務(wù)需求。例如，如果您的項(xiàng)目需要實(shí)現(xiàn)復(fù)雜的數(shù)據(jù)交互，您可能需要考慮使用其他 API 設(shè)計(jì)方法。
• 因此，請(qǐng)確保在選擇 API 設(shè)計(jì)方法時(shí)充分考慮您的業(yè)務(wù)需求。此外，您還需要確保 RESTful API 與您的系統(tǒng)架構(gòu)和技術(shù)棧相兼容。通過這些考慮，您可以確保 RESTful API 的正確使用，并且可以實(shí)現(xiàn)更高效和可靠的 API。
• 長(zhǎng)期來看，API 設(shè)計(jì)也不只是后端的工作，而是一個(gè)產(chǎn)品團(tuán)隊(duì)在產(chǎn)品設(shè)計(jì)上的協(xié)調(diào)工作，應(yīng)該整個(gè)團(tuán)隊(duì)參與。
• 這次簡(jiǎn)單分享了 API 與 RESTful API，在實(shí)際運(yùn)用中，并不是一定要使用這種規(guī)范，但是有 RESTful 標(biāo)準(zhǔn)可以參考，是十分有必要的，希望對(duì)大家有幫助。
• 如果您覺得這篇文章有幫助到您的的話不妨 關(guān)注+點(diǎn)贊+收藏+評(píng)論+轉(zhuǎn)發(fā) 支持一下喲~~ 您的支持就是我更新的最大動(dòng)力。
• 如果想跟我一起討論和學(xué)習(xí)更多的前端知識(shí)可以加入我的前端交流學(xué)習(xí)群，大家一起暢談天下~~~

參考資料