今天與另一位前端開發人員扯起了后端接口的皮（我也是前端人員），那個兄弟對后端人員提供的接口很大的意見（我是司空見慣），不過他說的也確實有道理，所以結合我的見解，希望提供接口的人員能多加注意。
1.沒有文檔...
例如新的前端人員到了一個新的公司，使用接口時，問這個這個不知道，問那個那個不知道，要文檔沒文檔，這絕對是前端人員最抓狂的事，心里肯定是一千只草泥馬奔騰而過。
為什么要文檔？
1. 文檔是當前開發者甚至后面的接盤俠（后面開發者）能夠清晰往下做的指引。
2. 即便是簡單的東西，但如果不寫文檔，以后口口相傳消耗的工作量會比寫文檔更多。
3. 好記性不如爛筆頭，一段時候后，可能連開發者都忘記接口的用途。
文檔怎么寫？
1. 在線文檔。
在線文檔易於更新和他人查看，例如可以使用Swagger編寫接口文檔。
PS：Swagger是一個規范和完整的框架，用於生成、描述、調用和可視化RESTful風格的Web服務。
2. 本地文檔。
本地文檔一般用Word文檔，但是比較不易傳播，但能離線查看。
Final~
文檔是及其關鍵的，無論是在線文檔還是本地文檔，有是關鍵。雖然寫文檔是麻煩的事，但對后端人員來說，是利人利己。
2.文檔不全...
額，就是有了文檔，文檔里面對接口的描述也可能不全，可能缺每個參數詳盡描述（取值范圍、類型）、請求方式（GET、POST、PUT、DELETE）、返回數據的所有狀態等等。這里面可能最缺就是返回數據的狀態！
一般的返回數據結構~
公司的數據接口返回結構是
{ s : 0/ 1, //表示此操作的處理狀態（ status ），一般簡單的成功 /不成功，使用 1/0 表示。 m : 'xxxx', //表示此操作的提示信息（ message ），一般只用來顯示操作失敗時提示信息。 r : [], //表示此操作的返回值（ result ） count : x //返回的數據條數 }
這種數據結構看起來沒問題，確實也沒大問題，問題就是出在s這個字段。有許多的接口不僅僅只有兩種狀態，成功狀態只有一種倒是沒問題，問題就出在失敗狀態，失敗可能有很多情況，一個簡單的s:0不能說明失敗的原因（即便是有m提示信息，但用這個來區分很不靠譜，因為提示可能會變化），我們不總是僅拿m做顯示用。
升級返回數據結構~
那位同事建議以下方式應答
{ s : 0/ 1/ 2/ 3, // 0代表正常，1是參數有誤，2是用戶不存在，3是用戶沒權限等等 m : 'xxxx', //表示此操作的提示信息（ message ），一般只用來顯示操作失敗時提示信息。 r : [], //表示此操作的返回值（ result ） count : x //返回的數據條數 }
m、r、count 可以保持不變，但是s里面必須包含所有返回狀態，代表這個接口所有業務的情況，前端開發人員也就能針對每種情況進行處理。
Final~
文檔最重要的部分是返回值的狀態，我也建議上面的升級返回數據結構，這樣就不存在任何不明朗情況。既然寫了文檔，就把文檔寫好，寫明朗，這也是利人利己地方。
3.接口參數沒校驗...
這個前端人員倒不是很關注，因為本身調接口之前都會先做校驗，后端做參數校驗只是雙重保證。我之前也做過一段時間后端，也犯過沒校驗參數的錯，額，因為后來沒有做后端，也就沒有去修正。不過還是提醒后端人員，做好參數校驗是第一步，不要偷懶了。
Final~
統一處理好接口校驗，后端好好考慮下。
4.沒保證接口原子性...
接口的原子性很重要，有時一個接口可能會干幾件事，但不一定都能正常完成，這就導致可能存在原子性問題，接口不能准確被調用。
PS：原子性。一個原子事務要么完整執行，要么干脆不執行。這意味着，工作單元中的每項任務都必須正確執行。如果有任一任務執行失敗，則整個工作單元或事務就會被終止。即此前對數據所作的任何修改都將被撤銷。如果所有任務都被成功執行，事務就會被提交，即對數據所作的修改將會是永久性的。
Final~
原子性一定要保證，保證，保證！
5.接口問題不斷...
前端開發人員調接口時候，可能會存在各自各樣的問題，有問題可以理解，程序哪會沒有bug，但不能太離譜啊，后端兄弟們。所以我覺得在給出接口之前自己明確幾件事：
1. 是否校驗參數。
2. 是否所有的情況都測試過了，如果可以請寫單元測試。
3. 是否返回數據准確明朗，響應狀態碼是否正常。
4. 文檔是否已經完備。
總結
后端人員多體諒前端人員，在出現問題時，先檢查自身，別一上來就跟前端干起來，要是自己的問題就尷尬了。
本文為原創文章，轉載請保留原出處，方便溯源，如有錯誤地方，謝謝指正。
本文地址 ：http://www.cnblogs.com/lovesong/p/5533149.html