原文：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個方案）