from------------------jackfrued

網(wǎng)絡(luò)API接口設(shè)計(jì)

手機(jī)App以及使用了Ajax技術(shù)或做了前后端分離的頁面都需要通過網(wǎng)絡(luò)API（Application Programming Interface）和后臺(tái)進(jìn)行交互，所謂API，指的應(yīng)用程序的編程接口；而網(wǎng)絡(luò)API通暢指的是基于HTTP或HTTPS協(xié)議的一個(gè)URL（統(tǒng)一資源定位符），通過這個(gè)URL我們可以讓服務(wù)器對(duì)某個(gè)資源進(jìn)行操作并返回操作的結(jié)果?；贖TTP(S)協(xié)議最大的好處就在于訪問起來非常的簡(jiǎn)單方便，而且沒有編程語言和應(yīng)用環(huán)境上的差別。

設(shè)計(jì)原則

關(guān)鍵問題

為移動(dòng)端或者PC端設(shè)計(jì)網(wǎng)絡(luò)API接口一個(gè)非常重要的原則是：根據(jù)業(yè)務(wù)實(shí)體而不是用戶界面或操作來設(shè)計(jì)。如果API接口的設(shè)計(jì)是根據(jù)用戶的操作或者界面上的功能設(shè)置來設(shè)計(jì)，隨著需求的變更，用戶界面也會(huì)進(jìn)行調(diào)整，需要的數(shù)據(jù)也在發(fā)生變化，那么后端開發(fā)者就要不停的調(diào)整API，或者給一個(gè)API設(shè)計(jì)出多個(gè)版本，這些都會(huì)使項(xiàng)目的開發(fā)和維護(hù)成本增加。

下面是某個(gè)網(wǎng)站開放API的接口，可以看出API的設(shè)計(jì)是圍繞業(yè)務(wù)實(shí)體來進(jìn)行的，而且都做到了“見名知意”。

注意：上面的API接口并不是REST風(fēng)格的，關(guān)于REST的知識(shí)，可以閱讀阮一峰老師的《理解RESTful架構(gòu)》以及《RESTful API設(shè)計(jì)指南》。

API接口返回的數(shù)據(jù)通常都是JSON或XML格式，我們這里不討論后者。對(duì)于JSON格式的數(shù)據(jù)，我們需要做到不要返回null這的值，因?yàn)檫@樣的值一旦處置失當(dāng)，會(huì)給移動(dòng)端的開發(fā)帶來麻煩（移動(dòng)端可能使用強(qiáng)類型語言）。要解決這個(gè)問題可以從源頭入手，在設(shè)計(jì)數(shù)據(jù)庫的時(shí)候，盡量給每個(gè)字段都加上“not null”約束或者設(shè)置合理的默認(rèn)值約束。

其他問題

1. 更新提示問題：設(shè)計(jì)一個(gè)每次使用系統(tǒng)首先要訪問的API，該API會(huì)向移動(dòng)端返回系統(tǒng)更新的相關(guān)信息，這樣就可以提升用戶更新App了。
2. 版本升級(jí)問題：API版本升級(jí)時(shí)應(yīng)該考慮對(duì)低版本的兼容，同時(shí)要讓新版本和舊版本都能夠被訪問，可以在URL中包含版本信息或者在將版本號(hào)放在HTTP(S)協(xié)議頭部，關(guān)于這個(gè)問題有很多的爭(zhēng)論，有興趣的可以看看stack overflow上面對(duì)這個(gè)問題的討論。
3. 圖片尺寸問題：移動(dòng)端對(duì)于一張圖片可能需要不同的尺寸，可以在獲取圖片時(shí)傳入尺寸參數(shù)并獲取對(duì)應(yīng)的資源；更好的做法是直接使用云存儲(chǔ)或CDN（直接提供了圖片縮放的功能），這樣可以加速對(duì)資源的訪問。

文檔撰寫

下面以設(shè)計(jì)評(píng)論接口為例，簡(jiǎn)單說明接口文檔應(yīng)該如何撰寫。

評(píng)論接口

全局返回狀態(tài)碼

1. GET /comments/{article-id}

   開發(fā)者：王大錘

   最后更新時(shí)間：2018年8月10日

   標(biāo)簽：v 1.0

   接口說明：獲取指定文章的所有評(píng)論

   使用幫助：默認(rèn)返回20條數(shù)據(jù)，需要在請(qǐng)求頭中設(shè)置身份標(biāo)識(shí)（key）

   請(qǐng)求參數(shù)：

   參數(shù)名	類型	是否必填	參數(shù)位置	說明
   page	整數(shù)	否	查詢參數(shù)	頁碼，默認(rèn)值1
   size	整數(shù)	否	查詢參數(shù)	每次獲取評(píng)論數(shù)量（10~100），默認(rèn)值20
   key	字符串	是	請(qǐng)求頭	用戶的身份標(biāo)識(shí)

   響應(yīng)信息：

   {
       "code": 10000,
       "message": "獲取評(píng)論成功",
       "page": 1,
       "size": 10,
       "totalPage": 35,
       "contents": [
           {
               "userId": 1700095,
               "nickname": "王大錘",
               "pubDate": "2018年7月31日",
               "content": "小編是不是有病呀",
               /* ... */
           },
           {
            "userId", 1995322,
               "nickname": "白元芳",
               "pubDate": "2018年8月2日",
               "content": "樓上說得好",
               /* ... */
           }
       ]
       /* ... */
   }
   

2. POST /comments/{article-id}

   開發(fā)者：王大錘

   最后更新時(shí)間：2018年8月10日

   標(biāo)簽：v 1.0

   接口說明：為指定的文章創(chuàng)建評(píng)論

   使用幫助：暫無

   請(qǐng)求參數(shù)：

   參數(shù)名	類型	是否必填	參數(shù)位置	說明
   userId	字符串	是	消息體	用戶ID
   key	字符串	是	請(qǐng)求頭	用戶的令牌
   content	字符串	是	消息體	評(píng)論的內(nèi)容

   響應(yīng)信息：

   {
       "code": 10001,
       "message": "創(chuàng)建評(píng)論成功",
       "comment": {
           "pubDate": "2018年7月31日",
           "content": "小編是不是有病呀"
           /* ... */
       }
       /* ... */
   }