很多人會(huì)談?wù)摻涌诨蛘?API 的定義。到底什么是接口定義？如何閱讀接口定義？

一、前端和后端

在談?wù)摻涌谥?，讓我們先明確前端和后端這兩個(gè)概念。

前端是我們?cè)诰W(wǎng)頁(yè)或移動(dòng)應(yīng)用程序中看到的頁(yè)面，它由HTML和CSS編寫而成，讓我們看到漂亮的頁(yè)面，并進(jìn)行一些簡(jiǎn)單的校驗(yàn)，例如確保必填字段不為空。后端則實(shí)現(xiàn)了頁(yè)面上的業(yè)務(wù)邏輯和功能，例如購(gòu)物和發(fā)布微博等功能。當(dāng)你在頁(yè)面上進(jìn)行這些操作時(shí)，后端會(huì)負(fù)責(zé)扣除余額或?qū)⑽⒉┌l(fā)布到指定的賬戶。那么前端和后端如何交互呢？這就是通過(guò)接口完成的。

雖然這些概念可能有點(diǎn)抽象，但你只需要記?。呵岸素?fù)責(zé)讓頁(yè)面看起來(lái)漂亮，后端負(fù)責(zé)實(shí)現(xiàn)網(wǎng)頁(yè)的功能。

無(wú)論是網(wǎng)頁(yè)還是安卓/iOS 客戶端，或者是微信小程序，或者是 Windows/Mac 上的軟件，都是同一個(gè)道理，都會(huì)區(qū)分前端和后端。前端就是在你的手機(jī)或者電腦上運(yùn)行的那個(gè)軟件，后端則是在服務(wù)器上運(yùn)行的那個(gè)軟件。

在公司里，前端和后端往往會(huì)分成不同的職位，他們開(kāi)發(fā)和實(shí)現(xiàn)的東西也截然不同。

二、接口

了解了前端和后端的概念，接下來(lái)就到接口了。

接口是一種通信機(jī)制，用于在前端和后端之間交換信息?？梢詫⑵湎胂鬄閮蓚€(gè)人之間在對(duì)話。

前端就像提問(wèn)者，而后端則像回答者。當(dāng)前端需要某些信息或執(zhí)行某些任務(wù)時(shí)，它會(huì)通過(guò)一個(gè)接口向后端發(fā)送請(qǐng)求。這個(gè)請(qǐng)求就像是一個(gè)問(wèn)題，告訴后端需要做什么。后端則會(huì)根據(jù)請(qǐng)求執(zhí)行相應(yīng)的操作，并將結(jié)果返回給前端。這個(gè)結(jié)果就像是答案，告訴前端完成了什么任務(wù)或提供了哪些信息。

這種交互就像一個(gè)問(wèn)答游戲，前端和后端通過(guò)接口不斷地問(wèn)答，從而實(shí)現(xiàn)應(yīng)用程序的功能和數(shù)據(jù)交換。例如，當(dāng)你在購(gòu)物網(wǎng)站上點(diǎn)擊“加入購(gòu)物車”按鈕時(shí)，前端會(huì)向后端發(fā)送一個(gè)請(qǐng)求，告訴它要將該商品添加到購(gòu)物車中。后端將執(zhí)行相應(yīng)的操作，并將結(jié)果返回給前端，告訴它是否成功添加了商品。

總之，接口就像是前端和后端之間的“對(duì)話”，用于交換信息和執(zhí)行任務(wù)。

接口又叫 API（Application Programming Interface）。我們一般講到接口或者 API，指的都是同一個(gè)東西。

三、接口定義

每個(gè)服務(wù)器都會(huì)提供不同的接口。比如，麥當(dāng)勞的點(diǎn)餐服務(wù)一定會(huì)提供以下幾個(gè)接口：

1. 查看菜單

2. 下單

3. 查詢我的訂單

你打開(kāi)麥當(dāng)勞的小程序時(shí)，小程序就會(huì)發(fā)起一個(gè)請(qǐng)求“查看菜單”，服務(wù)器會(huì)返回一個(gè)菜單數(shù)據(jù)，顯示在你的手機(jī)上。你選好餐，點(diǎn)擊“下單”的時(shí)候，就會(huì)發(fā)起一個(gè)下單請(qǐng)求，服務(wù)器就會(huì)返回“下單成功”。你在小程序點(diǎn)擊“我的訂單”的時(shí)候，也會(huì)發(fā)起一個(gè)查詢訂單的請(qǐng)求，服務(wù)器就會(huì)返回你的訂單列表。

以“下單”為例，下單肯定要包含消費(fèi)者的信息，以及消費(fèi)者點(diǎn)了什么餐。所以，小程序發(fā)起的下單請(qǐng)求就必須包含這些信息，否則就會(huì)下單不成功。同樣的道理，服務(wù)器返回的成功下單的詳情也必須包含這些信息，否則在小程序里就會(huì)顯示不完整。

也就是說(shuō)，開(kāi)發(fā)工程師在寫小程序和服務(wù)端的代碼的時(shí)候，就已經(jīng)規(guī)定好了信息交換的格式?？蛻舳苏?qǐng)求必須包含什么信息，服務(wù)端返回必須包含什么信息。這個(gè)規(guī)定就是接口定義。

而每個(gè)服務(wù)都會(huì)包含很多種不同的接口，比如上面提到的三種接口，它們都會(huì)各自有一套請(qǐng)求信息和返回信息的規(guī)定。

所以，接口定義就是軟件開(kāi)發(fā)時(shí)，對(duì)于前端如何請(qǐng)求信息，后端如何返回信息的結(jié)構(gòu)的規(guī)定。前后端都遵循相同的接口定義，使得不同的模塊之間可以互相協(xié)作，實(shí)現(xiàn)復(fù)雜的功能，同時(shí)保證系統(tǒng)的穩(wěn)定和可靠性。

四、接口定義的組成

一個(gè)接口的定義主要包含以下幾個(gè)部分：

1. 接口名稱：即接口的名稱或標(biāo)識(shí)符，用于區(qū)分不同的接口。

2. 接口方法：即接口所提供的方法，包括 GET、POST、PUT、DELETE 等。

3. 接口地址：即接口的訪問(wèn)地址。

4. 請(qǐng)求參數(shù)：即接口所需要的輸入?yún)?shù)，包括參數(shù)名稱、參數(shù)類型、參數(shù)說(shuō)明等。

5. 響應(yīng)參數(shù)：即接口所返回的輸出結(jié)果，包括返回值的類型、名稱、說(shuō)明等。

一個(gè)典型的接口定義是這樣的：

這個(gè)接口是在Apifox?里定義的。使用 Apifox 可以方便地進(jìn)行可視化的 API 定義、開(kāi)發(fā)、調(diào)試、測(cè)試。

五、閱讀主流廠商的 API 定義

對(duì) API 定義有了基本的了解之后，你可以閱讀主流大廠的 API 定義來(lái)加深對(duì)于 API 定義的理解。

在 Apifox 的 API Hub 提供了各家公司的開(kāi)發(fā) API，點(diǎn)擊訪問(wèn)：https://apifox.com/apihub/

例如，以下這個(gè)就是企業(yè)微信的 API 定義。

知識(shí)擴(kuò)展：

如果你想了解更多接口相關(guān)的使用技巧，可以查看以下文章：

• 如何讀懂常見(jiàn)的接口文檔？

• OpenAPI接口規(guī)范詳解，讓 API 開(kāi)發(fā)更加標(biāo)準(zhǔn)化