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

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

Swagger描述

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

　　

　　隨著前后端磨合，默契程度逐步增加，基本上這種描述文檔足夠聯調了。事物總是多變的，隨著新人的加入和接口的增加，業務的復雜化，過了大半年，回頭望月，接口已經開始出現壞味道。

　　

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

Wiki文檔

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

　　

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

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

圖文描述

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

　　

個人小結

1.對前端組件進行分類

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

2.接口數量要控制好

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

3.如何規范

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

?

后話

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

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

?

轉載于:https://www.cnblogs.com/jackyfei/p/9922275.html

總結

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

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。