希望給你3-5分鐘的碎片化學(xué)習(xí)，可能是坐地鐵、等公交，積少成多，水滴石穿，謝謝關(guān)注。

　　前后端分離的開發(fā)模式，假如使用的是基于RESTful API的七層通訊協(xié)議，在聯(lián)調(diào)的時候，如何避免配合過程中出現(xiàn)問題？這里分享一些不成熟的淺見。

Swagger描述

　　我們在前后端配合的過程中，使用了大多數(shù)人使用的Swagger作為服務(wù)描述文檔，這樣的好處很明顯，就是后臺編寫注釋，接口調(diào)用界面自動生成字段描述。如下圖：

　　

　　隨著前后端磨合，默契程度逐步增加，基本上這種描述文檔足夠聯(lián)調(diào)了。事物總是多變的，隨著新人的加入和接口的增加，業(yè)務(wù)的復(fù)雜化，過了大半年，回頭望月，接口已經(jīng)開始出現(xiàn)壞味道。

　　

　　新人不知道如何維護，連老人也要梳理回憶半天，接口膨脹導(dǎo)致分類不清晰，很難想象如果這個時候，如果你們需要把部分前端功能進行外包會怎樣？前端單看Swagger會不會一臉懵逼？

Wiki文檔

? ? ? ? 于是內(nèi)部開個了專題會，參照市面上大多數(shù)的api描述文檔，大家同意寫到wiki，雖然這種做法除了增加后端人員的工作量，對提升效率不是那么明顯，但是整個接口的描述相對就規(guī)范一些。

　　

　　過了一段時間，有一個前端新人進來，帶來了小小的煩惱，由于后端接口變更，文檔沒有及時更新，前端在聯(lián)調(diào)時候經(jīng)常一臉懵逼，如果能及時發(fā)現(xiàn)還好，否則將錯就錯，測試沒注意，發(fā)布后經(jīng)常犯一些寫錯別字的低級錯誤。

　　更加麻煩的是，項目工期趕，決定對前端部分模塊進行外包。于是準(zhǔn)備好了UI圖和接口描述文檔，覺得應(yīng)該可以安心了。承包方拿到UI和文檔的時候，除了簡單的增刪改查接口大概能猜的懂，其他的接口和UI上如何一一匹配？好吧，這該死的接口文檔。

圖文描述

　　于是后臺兄弟加班加點在UI上給每個功能一一標(biāo)注對應(yīng)的接口名稱，如下所示，雖然緩解了前端的困惑，但是前后端分離導(dǎo)致的一些效率損失，始終讓人耿耿于懷。也許就像DBA經(jīng)常說的，任何事物都是有代價，不知道大伙有更好的解決方案賜教？

　　

個人小結(jié)

1.對前端組件進行分類

比如樹、表格、下拉、radio、復(fù)選框、時間……越早分類對后面的管理應(yīng)該會更加有利，因為不同的新人進來，可能同樣的樹會重新造一種格式。

2.接口數(shù)量要控制好

?不能太多導(dǎo)致失控，也不能重復(fù)兩份接口（不同的開發(fā)者完全有這種可能），不同的前端組件比如easyUI和elementUI對格式要求是不一樣的，如果前后臺用的不是同一套UI框架，接口有可能會出現(xiàn)重復(fù)。

3.如何規(guī)范

每個公司規(guī)范不盡相同，可以參考大廠的規(guī)范，比如高德，微信或者百度地圖。對新入職的新要培訓(xùn)在前，開發(fā)中出現(xiàn)新的問題，最好要有專題會進行討論協(xié)商一致，最后口頭的東西務(wù)必要文檔化，否則都不能算是真正的規(guī)范。

?

后話

隨著團隊人數(shù)、業(yè)務(wù)擴大，如果沒有很好的規(guī)范，碰到溝通沖突的情況，規(guī)范就顯得特別重要。我們團隊原本兩個前后端配合融洽，相安無事，后面來了兩個新的前后端，由于言語沖突，一件簡單的小事會因為個性不合而被無限放大。盡快統(tǒng)一風(fēng)格，規(guī)范文檔化也許可以避免很多類似的問題。

這里給哪些想要做前后端分離的人一個不錯的RESTful API的規(guī)范，是阮一峰大神的博客，非常值得收藏，推薦下：RESTful API 最佳實踐

?

轉(zhuǎn)載于:https://www.cnblogs.com/jackyfei/p/9922275.html

總結(jié)

以上是生活随笔為你收集整理的RESTful API接口文档规范小坑的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。