api設計乾貨

shooke發表於2017-11-16

現在流行雲端化,前後端分離。要實現這樣的設計就必須開發介面。介面開發就好比一個產品換了包裝。業務邏輯上是沒有任何變化的,唯一變化的就是資料接收和返回做了新的處理。介面開發需要注意以下幾個基本點。

確定介面風格

到底你是採用傳統的風格,還是使用restful風格。這很重要,直接關係到你的介面長相,換句話說,讓對接你的人考到你的介面是什麼樣的。
比如微信的介面,採用的是傳統的風格,url中帶上token,post傳輸資料。
也有很多介面採用restful風格,特點就是介面地址比會變得簡短許多,資料的傳輸方式也多樣化,根據不同的目的選用不同的方式傳遞資料。比如get獲取資料,post新增資料,put修改資料。關於restful的詳情可以去網上查詢。這裡不做過多的闡述。

資料返回格式

這個很重要,一定要統一,設計之初就做好規劃。現在主流的方式是json、xml。json好處是資料量小,結構簡單已讀擴充套件性強。xml更加豐富,除了資料描述,還可以描述屬性資訊。當然json通過扁平化處理也是可以做到的,畢竟是物件嗎,一切皆物件。

狀態碼問題

一定一定一定不要把http狀態碼,和你的業務狀態碼混淆。
我見過最奇葩的設計把http狀態碼當做業務狀態碼返回,介面處理結構成功,直接放到header裡狀態碼用200,當出現錯誤的時候統一用500。
這樣的設計非常的糟糕,會增加你拍錯的難度,同時也會讓你混淆概念,分不清你的請求到底是失敗還是成功。
比如你請求一個列表,遇到一個404錯誤碼,你懷疑這個介面不存在是很正常的,但實際情況是介面找不到對應的資料,你去對接這個介面是不是很冤。打死也想不到因為這個列表沒有資料吧。
建議你這樣設計介面
介面根引數3個就夠了code,message,data這樣就可以描述你的介面了。

{
    code:0,
    message:'ok',
    data:{...} //如果是列表就data:[....]
}複製程式碼

這樣的返回結果一目瞭然。

code作為返回狀態,0表示成功,如果大於0則表示有錯誤。錯誤碼一定不能亂定,你可以根據介面情況分,也可以根據程式結構分。比如112001,前兩位表示某個類,中間兩位表示處理業務的方法,最後兩位表示錯誤代號,比如112001表示user類->login方法->報錯是缺少使用者名稱。這樣做的好處是你可以快速定位到底是哪個地方出現了問題。

message是錯誤說明,讓對接人員更容易理解發生了什麼

data存放資料,資料不管多麼複雜統統在data中進行擴充套件。

身份驗證

最為一個介面肯定不能讓人隨意折騰,一定要有一個機制去保護自己。所以一定有一個身份標示。以往的開發中我們用cookie或session儲存。在跟服務端互動的時候瀏覽器會自動傳送出去。但現在你是一個介面,也許來訪問你的不是瀏覽器,可能是任何方式。
我們可以設計一下身份標示的接受方式,可以是header中接收,現在前後端分離的開發中很常見,特別是用restful風格的介面,幾乎全是使用header方式傳遞身份標示。也可以是get方式接收,比如微信的介面,你會發現所有需要驗證的介面都會要求你跟上一個token引數。
當然了,也可以配合上其他安全措施,比如數字簽名,有效期等,提高安全性。

按照上面的幾點,你就可以開始設計自己的介面了。這裡沒有寫太過詳細的例子,我不想限制別人的思維,總之介面的開發要根據需求而定。沒有100分的標準答案,只有100%適合的方案。

相關文章