某神祕公司 RESTful、共用介面、前後端分離、介面約定的實踐

LonelyKeyGuest發表於2019-02-14


閱讀本文大概需要 4.6 分鐘。

 

本文來自

https://juejin.im/post/59eafab36fb9a045076eccc3

 

前言

隨著網際網路高速發展,公司對專案開發週期不斷縮短,我們面對各種需求,使用原有對接方式,各端已經很難快速應對各種需求,更難以提高效率。於是,我們不得不重新制定對接規範、開發邏輯以便快速上線專案。

我們的目標

  1. 儘可能的縮小溝通的成本,開最少的會,確定大部分的事。

  2. 花最少的時間寫文件,保證90%的開發人員看懂所有內容。

  3. 哪怕不看文件,也能知道各種介面邏輯。

  4. 不重複寫程式碼

  5. 儘可能的寫高可讀性的程式碼

我們做了哪些事

  1. 完成了前後端分離

  2. Android、ios、web共用一套介面

  3. 統一介面規範(post、put、get、patch、delete)

  4. 統一了除錯工具

  5. 統一了介面文件

之前的我們

介面是這樣子的:

 

介面地址 含義 請求方式

…/A專案/模組1/getProducts

獲得產品

GET

…/A專案/模組1/addProduct

新增產品

POST

…/A專案/模組1/getProductDetail

獲得產品詳情

GET

…/A專案/模組1/editProduct

修改產品

POST

客戶端請求是這樣的:

  • …/A專案/模組1/getProducts?id=1&a=2&b=3&c=4&d=5…………

  • A頁面=====》B頁面(攜帶n個變數)====》C頁面(攜帶m個變數,包含i個A頁面的變數) -------經常n>4

  • 大部分請求是POST,至於put、patch、delete是什麼鬼,關我屁事。

  • 關於介面入參使用json,那完全是看開發心情。

出參是這樣的:

{"message":"success","code":0,"data":具體內容}
其中data裡包含陣列可能是
[{"a":"1","b":"1"},{"a":"1","b":"1"},{"a":"1","b":"1"},{"a":"1","b":"1"}]
即使下一個頁面用到也不會使用id,而是把所有欄位都傳進去。
A介面中,返回產品用product;B介面中使用good,多個介面很可能不統一。

客戶端對接是這樣子的:

  • 安卓、ios一套;部分介面各自用一套;html5端一套。

  • 客戶端和後臺是不停交流的

介面文件是這樣的

img

img

  1. swagger

  2. 阿里的rap

  3. Word文件

  4. 其它

當然了,我覺得swagger和rap神器都是非常強大的,能夠實現各種功能邏輯,但是考慮到開發人員掌握程度不通,複雜度較高,難以提高效率,我決定初期並不使用這兩樣神器。

後端是這樣的

…/A專案/模組1/getProducts ----介面
…/A專案/模組1/Products.html ----頁面
…/A專案/模組1/Products.js ----靜態資源

介面和靜態資源纏在一塊,畢竟很多頁面可能是一位開發人員同時開發前端、後端,這裡的弊端是,只需要自己清楚邏輯,很多做法臨時應付,方案並不優雅,別人也很難看懂。一旦這位同事離職,很多說不清的邏輯就留給後人採坑了。

等等…………

重構

下面步入正題,面對以上眾多問題聊聊我是如何重新制定流程的

資料庫約定

約定資料庫裡所有表必須包含名為id主鍵欄位。
可能有人會說,正常來說不是每張表裡都應該有id主鍵嗎?但是,我們專案中由於之前開發不嚴謹,部分表沒有id主鍵,或者不為id的主鍵。這裡我們採用分散式的全球唯一碼來作為id。

api出參約定

約定所有出參裡含list,且其他請求會用到這組list,則list裡所有物件必須含id唯一標識。

入參約定

約定token身份認證統一傳入引數模式,後端採用aop切面程式設計識別使用者身份。其他引數一律為json。

resultfull介面約定

首先我們選擇一個名詞複數,比如產品

post方法

新增一條XXX
比如 ……/products 則代表新增一條產品
入參json如下:

{    "name":"我是一款新產品",    "price":100,    "kind":"我的分類",    "pic":[一組圖片],    等等還有很多}

java 程式碼control層

    @ResponseBody    @RequestMapping(value = "/A專案/B模組/products", method = {RequestMethod.POST})    public ResultObject getProducts() {        //具體邏輯。    }

put方法

新增某條XXX記錄
比如 ……/products/1111111111
入參json如下:

{    "name":"我是一款新產品",    "price":100,    "kind":"我的分類",    "pic":[一組圖片],    等等還有很多}

表示增加一條1111111111id的記錄
java程式碼control層

    @ResponseBody    @RequestMapping(value = "/A專案/B模組/products/{id}", method = {RequestMethod.PUT})    public ResultObject putProducts(@PathVariable(value = "id") String id) {        //具體邏輯。    }

get方法

獲得所有XXX
……/products 則代表獲取所有產品
因為有分頁,所以我們後面加了?page=1&pageSize=50

我們約定了所有名詞複數,都會返回list,且list每個物件都有欄位為id的唯一id。
比如

{    "data":{"list":[{"id":"唯一id","其他很多欄位":""},{"id":"唯一id","其他很多欄位":""}],"page":1,其他欄位},    "code":0,    "message":"成功"}

……/products/{id} 獲取某個具體產品(一定比列表更詳細)

比如某個具體產品裡還包含一個list,如該產品推薦列表,則:
……/products/{id}/recommendations

假設它包含的不是一個list,而是物件,比如產品佣金資訊,則:
……/products/{id}/Commission

這裡我們以是否名詞複數來判斷是物件還是list.

java程式碼control層

    @ResponseBody    @RequestMapping(value = "/A專案/B模組/products/{id}", method = {RequestMethod.GET})    public ResultObject putProducts(@PathVariable(value = "id") String id) {        //具體邏輯。    }

patch 方法

更新區域性XXX產品YYY資訊
入參是post方法時入參的子集,所有支援更新的引數會說明,並不是支援所有變數
……/products/{id}

{    "name":"我是一款新產品",    "price":100,    部分變數}

java程式碼control層

    @ResponseBody    @RequestMapping(value = "/A專案/B模組/products/{id}", method = {RequestMethod.PATCH})    public ResultObject putProducts(@PathVariable(value = "id") String id) {        //具體邏輯。    }

delete方法

刪除XXX記錄
……/products/11111

刪除11111產品。
java程式碼control層

    @ResponseBody    @RequestMapping(value = "/A專案/B模組/products/{id}", method = {RequestMethod.DELETE})    public ResultObject putProducts(@PathVariable(value = "id") String id) {        //具體邏輯。    }

其他說明

我們儘可能少的使用動詞,但有一些行為需要使用動詞,比如登入等。
關於版本號,我們打算在模組後增加/v1/等標識。

許可權約定

服務端要對使用者角色進行判斷,是否有許可權執行某個邏輯。

前後端分離約定

後端以開發介面為主,不再參與頁面開發,或者混合式jsp頁面開發,統一以介面形式返回,前端通過js渲染資料以及處理邏輯。

共用介面

web、Android、ios使用統一介面,不在因為哪方特殊要求額外開放介面。

使用統一dao層生成工具

基於mybatis-generator改造成適合我們專案的dao層以及部分service層,內部共同維護共同使用。

使用postman最為介面文件、除錯工具

雖然有上文中介紹的rap和swagger都是特別牛的介面神器,但是我們還是選擇了postman,開發人員將介面名稱、說明、入參、出參,以及各種出參示例都儲存,這樣開發直接可以看得清介面含義。

我們建議使用瀏覽器外掛,這裡以360極速瀏覽器為例。
外掛下載地址:https://download.csdn.net/download/qq273681448/10033456

開啟360瀏覽器擴充套件中心,然後勾選開發者模式,再點選載入已解壓的擴充套件程式,選中壓縮包解壓後的目錄,最後點選執行即可。

img

其中出參註釋、及介面說明,寫在tests裡:

/*這裡是介面說明,和每個出參、入參的意思。*/

img

介面按模組劃分為資料夾:

img

入參:

img

出參示例:

img

正常請求:

img

開發人員即可直接看到介面示例進行開發,而開發人員開發的時候,自己呼叫一次即可儲存為postman檔案,為了加快上線,我們允許將java中實體類變數定義的程式碼(含註釋)直接複製貼上出來。

js等靜態資源快取問題

從短期角度上講,我的要求是減少js檔案的變更,如果有變更,務必更改版本號。那麼如何減少修改,我們的做法是將一部分js寫在html內,反正前後端分離,大不了重新整理一下cdn的節點快取,畢竟大部分瀏覽器也不會主動快取html檔案(大部分瀏覽器會快取js等檔案)。

統一js請求框架

這裡我們使用angular js的請求框架,因為我們內部對angularjs使用較多,比較熟悉,封裝後的請求,可以自動彈窗錯誤請求,可複寫錯誤回撥。

目前效果

目前,我們客戶端看到介面,大概能說出其意思,也能猜出一連串介面的含義,比如
……/classes
可以看出它是獲取班級列表介面,猜到

……/classes/id get獲取id為id的班級詳情
……/classes/id patch 修改班級資訊
……/classes/id delete 刪除班級資訊

至於入參,patch是post的子集、put=patch、delete無入參。

而入參含義,直接開啟postman可以直接檢視每個欄位的含義,並且,可以實時調取開發環境資料(非開發人員電腦),這裡我們使用了多環境。

前端使用統一封裝後的js請求框架也加快了開發進度,不用造輪子。

開發人員,一般程式碼開發寫好,使用postman自我測試,測試完成後,介面文件也就寫好了。

測試人員想了解介面文件的也可以直接使用postman進行匯入檢視。

至此,我們交流成本下降了一大半,剩下開會的內容就是按ui分解需求或者按ui施工了。

總結

經過一番的折騰,開發進度總算快了點,也一定程度上達到了快速上線專案的效果。關於restful風格api,每個人都有自己的見解,只要內部約定清楚,能儘可能少的減少溝通,我覺得就是好的理解。

至於介面工具,可能很多人會說為什麼不用之前的,我覺得以後還是會用的,最好能做到外掛自動化生成api,但是對java開發註釋要求比較嚴格,隨意慢慢來吧,畢竟後面我們還有很多路要走。

 

 

 

往期精彩回顧
 

相關文章