先說說啥是

Api

吧，以下摘自百度百科：

API

（Application Programming Interface，應用程式程式設計介面）是一些預先定義的函式，目的是提供應用程式與開發人員基於某軟體或硬體得以訪問一組例程的能力，而又無需訪問原始碼，或理解內部工作機制的細節。

其實對於我們接觸的

web

端開發而說，

Api

就是協商好的一種規範，大家都按這個規範做事，這裡主要針對

前&後端互動的介面

進行說明。

返回值約定

返回值是指當前端返回後端給出的介面時返回的資料格式，常見的有這麼幾種：

text

，

json

，

xml

，現在大多數會用

json

，因為她傳輸資料少，可擴充套件性強，B格高～

方式一

我們約定返回值如果包含

errcode

則視為有錯誤，並會出現可選的

msg

欄位，無錯誤則使用

items

表示迴圈的資料，格式如：

//提交成功，沒有返回資料{}//獲取成功，返回列表資料{ “items”：［ { “id”： 1， “name”： “前端小武” } ］}//獲取失敗，{ “errcode”： 1}//提交失敗{ “errcode”： 1， “msg”： “使用者名稱為空”}//返回一個連結{ “url”： “/login/”}

這種格式通常

errcode

會有一個公用的錯誤碼，比如

1001

沒登入，

2001

使用者被鎖定等，注意的是這個值是強制型別，前端判斷：

function success （res）{ if（res。errcode）{//有錯了 if（res。errcode === 1001）{ alert（‘請先登入’）； } else { //no } } else { //成功 }}

方式二

約定返回值必須有

errcode

，為

0

則是成功，否則失敗，

errcode

也會對應公用的狀態碼，

msg

可選，

data

為資料，比如：

//成功{ “errcode”： 0}//提交失敗{ “errcode”： 1， “msg”： “引數錯誤”}//獲取連結{ “errcode”： 0， “data”： “/”}//獲取列表{ “errcode”： 0， “data” ［］}

還有就是返回狀態碼，通常使用

200

，然後用

errcode

表示，但也有些以

401

未登入，

403

許可權驗證失敗等~

返回值的格式大家約定好按著寫就行，沒有什麼好與不好～

介面的路徑風格

路徑是指後端提供給前端呼叫該介面的地址，其實就是該介面的連結，最好以一個較為明顯的詞為目前開頭，或者說以單獨的域開頭，路徑還要向語義化靠攏，這裡只是路徑，不涉及到引數，比如：

/api/user/info

http：//api。xuexb。com/user/info

注：通常是

複數

時會在詞後加

s

，比如照片是

photo

，但照片集，多個照片時是

photos

，當然這不是硬性規定，具體還要看你～

隱式語義化風格

/api/photos/

獲取所有照片列表，類似預設的

index

為主頁的意思

/api/photos/create

建立照片

/api/photos/delete

刪除照片

/api/photos/update

更新照片

/api/photos/{id}

獲取單個照片資訊

顯式語義化風格

/api/photos/get-list

獲取照片列表

/api/photos/create

建立照片

/api/photos/delete

刪除照片

/api/photos/set

更新

/api/photos/set-xx

更新某項

/api/photos/get/{id}

建立單個

restful

REST

是一種風格，也可以說是一種思想，現在已經被廣泛的應用於客戶端介面的開發，這是一種以提交型別來約定行為的，比如：

GET /api/article

獲取所有的article列表

GET /api/article/10

獲取id為10的article詳細資訊

POST /api/article

新增一個article

PUT /api/article/10

更新id為10的article資料

DELETE /api/article/10

刪除id為10的article資料

檢視更多關於

restful

的資訊：

http：//www。ruanyifeng。com/blog/2014/05/restful_api。html

引數

引數分必選和可選，分資料型別，欄位說明，如：

文件

我也曾有過一個不堪回首的往事，曾是沒有文件的時候都是以“喊話”為途徑，直接就是：xx我登入傳一個使用者名稱和密碼，返回1或0～然後我發現這TMD就是個坑，當時間長了，要修改邏輯時天知道這介面是啥東西，天又知道這欄位是啥意思，天知道出了

bug

應該如何除錯～後來我就用

excel

來寫，但是因為不是二進位制造成是覆蓋式提交，想比對檔案差異都沒辦法，於是我後來使用

markdown

來寫介面，我現在感覺我愛上她了，用

md

寫文件後可以線上的瀏覽，甚至可以線上編輯，很方便，當然這得後端語言的支援，不過我相信作為前端的你應該完全可以用

nodejs

搞定她～

介面文件常用的欄位：

名稱，該介面的名稱

備註，該介面的一些使用場景，注意問題等說明

路徑，表明出訪問該介面的地址

返回值格式，通常為

json

請求方式，請求該介面的方式

引數，詳情列出介面需要的引數，分可選、必選

返回欄位說明，以文字描述出返回值比較重要的欄位

返回值例子，分多種狀態列出該介面可能出現的返回值

文件 demo

版本控制

如果在客戶端應用介面還要涉及到版本控制，比如你發的

App1。0

使用的介面跟

2。0

使用的可能不一樣，可能會有介面欄位調整，型別調整等，這時你又不能丟棄老的使用者，還要相容新的版本，那麼這樣的版本總體來說可以分大版本和小版本

大版本

以版本號為路徑，比如

/api/v1/*

，在

App

做一次大的升級，會出現多個介面大的遷移，這時要考慮到資料庫的相容，在適當時候整體新版本里應用

v2

資源，當然這個應該是在

App

載入的時候獲取的配置檔案裡帶的，升級大版本後相關調整的介面一定要跟客戶端開發者約定好，避免相容問題

小版本

實際工作中難免會經常

fix

一些問題，或者小的需求改動，比如在登入里加個驗證碼，這小的改動遵循

只新增不刪除

的規則，因客戶端在請求介面時都會帶有

App

當前的版本號，後端可根據該版本來做一些相容，比如

1。0。1

的時候登入不用驗證碼，

1。0。2

的時候必須有驗證碼這樣的需求，當然還有一些裝置的相容，比如

ios

和

android

等，當一個接口裡小的版本過多時就得考慮升級了

最後說：版本的升級是件“大事”，一定要跟所有的相關人員密切的溝通，當然希望你的溝通者是女的吧～