公司前端和后端工程師，因為接口吵起來啦，還列了 5 鍋罪！

板橋胡同37號 2021-04-04

展開全文

罪狀一：沒有文檔
罪狀二：文檔不全
罪狀三：接口參數沒校驗
罪狀四：沒保證接口原子性
罪狀五：接口問題不斷

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

罪狀一：沒有文檔

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

1.為什么要文檔？

文檔是當前開發(fā)者甚至后面的接盤俠（后面開發(fā)者）能夠清晰往下做的指引。
即便是簡單的東西，但如果不寫文檔，以后口口相傳消耗的工作量會比寫文檔更多。
好記性不如爛筆頭，一段時候后，可能連開發(fā)者都忘記接口的用途。

2.文檔怎么寫？

在線文檔。

在線文檔易于更新和他人查看，例如可以使用Swagger編寫接口文檔。

PS：Swagger是一個規(guī)范和完整的框架，用于生成、描述、調用和可視化RESTful風格的Web服務。

本地文檔。

本地文檔一般用Word文檔，但是比較不易傳播，但能離線查看。

Final~

文檔是及其關鍵的，無論是在線文檔還是本地文檔，有是關鍵。雖然寫文檔是麻煩的事，但對后端人員來說，是利人利己。

罪狀二：文檔不全

額，就是有了文檔，文檔里面對接口的描述也可能不全，可能缺每個參數詳盡描述（取值范圍、類型）、請求方式（GET、POST、PUT、DELETE）、返回數據的所有狀態(tài)等等。這里面可能最缺就是返回數據的狀態(tài)！

一般的返回數據結構~

公司的數據接口返回結構是

{
s : 0/ 1, //表示此操作的處理狀態(tài)（ status ），一般簡單的成功 /不成功，使用 1/0 表示。
m : 'xxxx', //表示此操作的提示信息（ message ），一般只用來顯示操作失敗時提示信息。
r : [], //表示此操作的返回值（ result ）
count : x //返回的數據條數
}

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

升級返回數據結構~

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

{
s : 0/ 1/ 2/ 3, // 0代表正常，1是參數有誤，2是用戶不存在，3是用戶沒權限等等
m : 'xxxx', //表示此操作的提示信息（ message ），一般只用來顯示操作失敗時提示信息。
r : [], //表示此操作的返回值（ result ）
count : x //返回的數據條數
}

m、r、count 可以保持不變，但是s里面必須包含所有返回狀態(tài)，代表這個接口所有業(yè)務的情況，前端開發(fā)人員也就能針對每種情況進行處理。

Final~

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

罪狀三：接口參數沒校驗

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

Final~

統(tǒng)一處理好接口校驗，后端好好考慮下。

罪狀四：沒保證接口原子性

接口的原子性很重要，有時一個接口可能會干幾件事，但不一定都能正常完成，這就導致可能存在原子性問題，接口不能準確被調用。

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

Final~

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