公司前端和後端因為介面扯起了皮，還列了 5 宗罪

今天一位前端開發人員扯起了後端介面的皮，那個兄弟對後端人員提供的介面很大的意見（我是司空見慣），不過他說的也確實有道理，所以結合我的見解，希望提供介面的人員能多加注意。

例如新的前端人員到了乙個新的公司，使用介面時，問這個這個不知道，問那個那個不知道，要文件沒文件，這絕對是前端人員最抓狂的事，心裡肯定是一千隻草泥馬奔騰而過。

1.為什麼要文件？

文件是當前開發者甚至後面的接盤俠（後面開發者）能夠清晰往下做的指引。

即便是簡單的東西，但如果不寫文件，以後口口相傳消耗的工作量會比寫文件更多。

好記性不如爛筆頭，一段時候後，可能連開發者都忘記介面的用途。

2.文件怎麼寫？

ps：swagger是乙個規範和完整的框架，用於生成、描述、呼叫和視覺化restful風格的web服務。

本地文件。

本地文件一般用word文件，但是比較不易傳播，但能離線檢視。

final~

額，就是有了文件，文件裡面對介面的描述也可能不全，可能缺每個引數詳盡描述（取值範圍、型別）、請求方式（get、post、put、delete）、返回資料的所有狀態等等。這裡面可能最缺就是返回資料的狀態！

一般的返回資料結構~

公司的資料介面返回結構是

這種資料結構看起來沒問題，確實也沒大問題，問題就是出在s這個字段。有許多的介面不僅僅只有兩種狀態，成功狀態只有一種倒是沒問題，問題就出在失敗狀態，失敗可能有很多情況，乙個簡單的s:0不能說明失敗的原因（即便是有m提示資訊，但用這個來區分很不靠譜，因為提示可能會變化），我們不總是僅拿m做顯示用。

公升級返回資料結構~

那位同事建議以下方式應答

m、r、count 可以保持不變，但是s裡面必須包含所有返回狀態，代表這個介面所有業務的情況，前端開發人員也就能針對每種情況進行處理。

final~

文件最重要的部分是返回值的狀態，我也建議上面的公升級返回資料結構，這樣就不存在任何不明朗情況。既然寫了文件，就把文件寫好，寫明朗，這也是利人利己地方。

這個前端人員倒不是很關注，因為本身調介面之前都會先做校驗，後端做引數校驗只是雙重保證。我之前也做過一段時間後端，也犯過沒校驗引數的錯，額，因為後來沒有做後端，也就沒有去修正。不過還是提醒後端人員，做好引數校驗是第一步，不要偷懶了。

final~

統一處理好介面校驗，後端好好考慮下。

介面的原子性很重要，有時乙個介面可能會幹幾件事，但不一定都能正常完成，這就導致可能存在原子性問題，介面不能準確被呼叫。

ps：原子性。乙個原子事務要麼完整執行，要麼乾脆不執行。這意味著，工作單元中的每項任務都必須正確執行。如果有任一任務執行失敗，則整個工作單元或事務就會被終止。即此前對資料所作的任何修改都將被撤銷。如果所有任務都被成功執行，事務就會被提交，即對資料所作的修改將會是永久性的。

final~

原子性一定要保證，保證，保證！

前端開發人員調介面時候，可能會存在各自各樣的問題，有問題可以理解，程式哪會沒有bug，但不能太離譜啊，後端兄弟們。所以我覺得在給出介面之前自己明確幾件事：

是否校驗引數。

是否所有的情況都測試過了，如果可以請寫單元測試。

是否返回資料準確明朗，響應狀態碼是否正常。

文件是否已經完備。

後端人員多體諒前端人員，在出現問題時，先檢查自身，別一上來就跟前端幹起來，要是自己的問題就尷尬了。