先後端交互-一些關於接口設計的思考

原文：https://blog.csdn.net/u014315849/article/details/78567399

場景：主要是微信端網頁開發，前端每每是先打開頁面而後經過Ajax向後臺發送請求返回JSON格式的數據。

原則一：一個頁面儘可能只有一個拉取接口

主要考慮的是儘可能減小請求連接數，請求連接數越多，因爲網絡緣由，出現異常的可能性越大。

原則二：打破規則一，當請求須要緩存而且有須要及時更新的狀況

爲了更好的打開速度，對於不常常變化的數據，每每須要作數據緩存以及請求緩存。但有些信息，好比預定時間，又須要作到及時，則應該分多個請求。

原則三：若是返回數據中某個字段的數據沒有，返回該字段比不返回該字段要好。

JSON格式的好處在於靈活性，但沒有校驗機制。因此定義協議時規定了有哪些字段，最好這些字段都返回。個人意思是好比返回一個列表，大多數場景是返回一個數組，但若是沒有數據，返回一個空數組比不返回該字段要好。固然前端也有必要作本身的容錯考慮。

其餘：

1.比較常見的返回數據的格式，經驗有限，也不清楚這是否是最優的。

{
    status: "", message: "", data: { } }

2.這裏有一篇關於HTTP API設計指南，感受挺好的，但本身實際應用的很少。

前言

最近在工做中和後端童鞋打交道，先後端溝通最爲重點的就是接口API,這裏整理一下接口設計的一些考慮點並作分析，但願對你們有幫助 。

兵馬未動，糧草先行。在一款APP產品的各個版本迭代中，兵馬的啓動指的是真正開始敲代碼的時候，糧草先行則是指前期的需求，交互，UI等評審準備階段，還有本文要說的接口的設計與評審。雖然不少時候一個api接口的業務，數據邏輯是後端提供的，但真正使用這個接口的是客戶端，一個前端功能的實現流程與邏輯，有時候只有客戶端的RD才清楚，從某種意義來講，客戶端算是接口的需求方。

因此建議在前期接口設計和評審時，客戶端的RD應該更多的思考和參與，什麼時機調什麼接口？每一個接口須要哪些字段？數據含義怎麼給？只有這些都考慮清楚，且達成一致併產出接口文檔後，當項目真正啓動時，根據接口協議進行開發，才能儘可能避免各類不肯定因素對項目總體進度的影響。

接口設計的考慮點

我從下面幾個方面考慮接口的設計：

• 1 接口文檔

• 2 接口安全

• 3 一些基本原則

• 4 瘦客戶端

---

1 關於接口文檔

1.1 接口設計必須提供接口文檔

不管項目團隊的大小，在遇到接口問題的時候單純的從代碼出發，而不是從接口文檔出發，對於整個項目團隊的維護簡直就是耍流氓。

1.2 文檔也應歸入版本控制

使用markdown,wiki 作文本類型的文檔，使用svn，git等作爲版本工具 能夠很清晰的看到接口文檔的改動人和改動時間，一樣是方便維護工做。

1.3 文檔類型選擇markdown,wiki等

使用文本類型的文檔（好比markdown, wiki等格式），一則方便比較版本間改動，二則能夠生成html, word, pdf等多種美觀格式。我見過有好多團隊是使用word來寫文檔的，因爲是二進制格式，不利於版本比較，也不專業。

1.4 文檔- 簡潔

檔不該浮於形式，而是力求只寫最有價值的內容。作好這一點的關鍵是做者與讀者要有足夠的約定，好比蠶繭法就能很好的幫助簡化類型定義的描述。

1.5 應有機制保證接口文檔與代碼的一致

一些團隊在文檔上應付差事浮於形式，在代碼寫完後，補一個word文檔應付。在更新代碼時，文檔沒有及時更新，致使文檔都是錯誤無法看。好的作法都應先有設計再寫代碼，好比架構師或主程先設計好接口，而後再開始編程實現，在實現中發現問題再修正接口，更新設計文檔，而不該是寫完代碼再補個設計。而在文檔更新的具體作法上，也流行一種作法即文檔以註釋的方式內嵌於代碼中，我稱之爲「格式化註釋」，這樣作到設計與代碼在一塊兒，更新也就更天然的同步了。以後再經過工具將註釋抽出來美化給讀者看。

1.6 接口應當包含內容

接口地址、請求方法、請求參數、返回內容、錯誤代碼 
- 如下是一個用戶信息接口的文檔示例，包含接口描述，請求參數，響應參數，json示例等。

接口描述：用戶登錄成功後，或進入我的中心時會獲取一次用戶信息 

"code":200, "msg":"成功", "time":"1482213602000", "data": { "id":"1001", "name":"張三", "age":"20" } }

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9

---

2 接口安全

當咱們面對不少外部接口的時候，咱們須要考慮數據的安全性。爲何要考慮安全性：

• 包含用戶數據
• 包含交易數據
• 以及甚至你不想讓用戶本身知道的數據

因此分爲請求參數和響應參數： 
- 請求參數中包含用戶隱私的字段參數，如：登錄接口的密碼字段，須要進行加密傳輸，避免被代理捕捉請求後獲取明文密碼。

• 響應參數中包含用戶隱私的字段數據，須要加*號。如：手機號，身份證，用戶郵箱，支付帳號，郵寄地址等。

"phone":"150*****000", "idCard":"3500**********0555", "email":"40*****00@qq.com" }

• 1
• 2
• 3
• 4

• 客戶端和服務器經過約定的算法，對傳遞的參數值進行簽名匹配，防止參數在請求過程當中被抓取篡改

保護接口的方式最基本的是SSL/TLS，而後呢：

• 對稱加密的方式
• 非對稱加密的方式
• 動態祕鑰

具體能夠看 像架構師同樣來思考微服務接口設計

---

3 接口的一些原則

3.1 一個頁面儘可能只有一個拉取接口

原先一個頁面要經過多個請求獲取多種類型數據的狀況，最好能經過一個接口所有獲取獲得。又如：在調用B接口前須要A接口的前置數據的狀況，可讓後端支持下，在調用A接口時直接返回B接口的數據，減小相似這種的連續請求。

3.2 打破第一條規則，當請求須要緩存而且有須要及時更新的狀況

爲了更好的打開速度，對於不常常變化的數據，每每須要作數據緩存以及請求緩存。但有些信息，好比預定時間，又須要作到及時，則應該分多個請求。

3.3 若是返回數據中某個字段的數據沒有，返回該字段比不返回該字段要好。

JSON格式的好處在於靈活性，但沒有校驗機制。因此定義協議時規定了有哪些字段，最好這些字段都返回。個人意思是好比返回一個列表，大多數場景是返回一個數組，但若是沒有數據，返回一個空數組比不返回該字段要好。固然前端也有必要作本身的容錯考慮。

比較常見的返回數據的格式： 

3.4 命名規範

統一命名：與後端約定好便可（php和js在命名時通常採用下劃線風格，而Java中通常採用的是駝峯法），無絕對標準，不要同時存在駝峯」userName」，下劃線」phone_number」兩種形式就能夠了。

避免冗餘字段：每次在新增接口字段時，注意是否已經存在同一個含義的字段，保持命名一致，不要同時存在」userName」，」username」，」uName」多種同義字段。

註釋清晰（重要）：每一個接口/字段都須要有詳細的描述信息，不少時候接口體現業務邏輯，是團隊中很重要的文檔沉澱，同時，詳細的接口文檔，能夠幫助新人快速熟悉業務。

3.5 將APP接收數據的類型定義爲容錯能力更強的String（推薦）

容錯性強，規避因髒數據引發的數據解析失敗。

---

4 瘦客戶端

衆所周知，客戶端任何的修改都是須要發版的，特別是IOS須要走AppStore的審覈流程。爲了修一個bug，僅僅改幾行代碼，而從新走一輪發版流程，是很勞民傷財的。因此在接口設計的時候，也須要適當考慮這點，將業務重心交由後端，客戶端保持邏輯簡單。後端一天能夠發n個版，客戶端一個版本卻只能發一次，有些團隊一開始並沒意識到這點，總覺後端就是重度業務邏輯的所在，管那麼多前端的展現，真正到了出問題（bug或需求變動）須要發版的時候，雖然70%的鍋是客戶端背，可是，剩餘30%也會對當初重客戶端的選擇然後悔，不太重點不是誰背鍋，而是產品不出問題。so，爲了大局，後端的RD們，咱們得聊聊。

4.1 客戶端儘可能只負責展現邏輯，不處理業務邏輯

例如：客戶端有個TextView，後端只給個status字段，status=1時，展現文案1；status=2時，展現文案2；這樣設計的缺點是，若是之後要修改status=3時，展現文案1，那麼這個status判斷邏輯時寫死在客戶端，就沒辦法支持這種修改，且這種設計限定死了TextView只能展現2種文案。推薦方案是後端直接將TextView須要展現的文案下發，這樣無論是status的判斷，仍是文案的展現，後期都是可變的。

4.2 客戶端不處理金額的計算

例如：外賣APP，用戶在下單的時候，須要選擇收貨地址，支付類型，優惠券等，任何一個選項的修改，均可能影響用戶最後須要支付的金額。因此這裏比較常見的接口設計是在每次選擇完回到訂單支付頁面後，再發送一次請求，後端根據當前選項從新計算金額。金額永遠是一款產品最重要，最敏感的信息，若是交由客戶端計算，萬一出錯，即便少1分，都是毀滅性的，因此，關於金額，展現就好。

4.3 客戶端少處理請求參數的校驗與約束提示

例如：修改密碼功能，密碼規則」6-12字母，數字，下劃線」，有3種作法： 
- 1 在發送請求前，客戶端校驗密碼規則，若是不符合，則不發送請求。優勢：規則不知足時，能夠減小沒必要要的請求。缺點：客戶端寫死校驗邏輯，密碼規則變化時，客戶端須要發版。

• 2 客戶端只判斷null，和最短位數限制，其餘校驗規則交由後端處理。優勢：靈活性最好。缺點：後端壓力大，校驗請求多。

• 3 後端在通用配置的接口返回正則表達式，客戶端獲取後進行正則校驗。優勢：具備必定靈活性。缺點：開發，調試成本較高。（推薦：即便出問題，也能夠清除配置，回退到第2個方案）