ZanApi 讓先後端協調更高效

1、當咱們在說先後端協做的時候，咱們在說什麼

目前先後端分離已成爲主流，先後端開發環境互相獨立的狀況下，如何提升先後端協做效率已然成爲每一個公司不得不考慮的問題。

以一個項目開發週期爲例，在協做上通常須要面對如下幾個問題：

1. 項目開發初期，先後端須要就接口定義達成一致而且最好能在一個地方持久化，而且隨着項目迭代開發持續維護
2. 先後端在並行開發時前端須要先對接口數據進行 mock
3. 項目聯調前，對於前端同窗來講，咱們須要能科學的判斷後端同窗的接口是否真的達到可聯調狀態了

2、有贊以前是怎麼作的

1. 對於接口定義

我相信不少公司跟有贊同樣，沒有專門的API文檔站點，也沒有相應的工具，基本在一個通用的文檔站點由工程師本身手動建立、維護接口文檔。

有贊也一樣使用這種方式去維護接口文檔，但這種方式會帶來一些比較明顯的問題：

1. 建立、維護成本大，在後端同窗比較忙的狀況下，不見得能夠及時提供、更新文檔。
2. 手動編寫容易出錯。
3. 因爲是通用的文檔站點，接口文檔展現並非很是直觀。

這些問題都會增長協做雙方的溝通成本，進而影響項目總體進度。

2. 對於數據 mock

前端同窗對於接口數據 mock 應該是很是熟悉的，並且每一個公司或多或少都會有本身的一些套路跟方案。

好比最開始，你們可能會使用在前端代碼裏面直接寫死 mock 數據的方式。你可能會對下面這段代碼比較熟悉：

import mockData from './mockdata.js'

// ajax(url).then(dosomething)
// 數據 mock

setTimeout(mockData => {
    dosomething(mockData);
}, 1000);

經過這種方式，前端同窗能夠在開發階段手動 mock 後端接口數據，從而實現並行開發。

但這種方式的缺點顯而易見：

1. setTimeout 顯然是沒法徹底模擬 ajax 的行爲的。
2. 上線前須要修改代碼，從新打包。
3. 由於有缺點2，會引入額外的風險點。（忘記修改從新打包）
4. 是否要保留 mock 數據和相應的邏輯以便以後項目迭代。
5. 若是後端接口變動，沒法及時響應（依賴於先後端口頭通知）

由於這些缺點和 nodejs 的崛起，前端同窗天然會想到使用 node 作一套 mock 服務器。因而就有了下面這種方式：

// ajax(realUrl).then(dosomething)

ajax(mockUrl).then(dosomething)

這種方式解決了使用 setTimeout 模擬真實請求的問題而且極大的減小了 mock 功能對業務的侵入。並且由於 mock 數據在遠程，先後端可同時修改，減小溝通成本。

可是這種方式仍是沒法解決問題 2、3、4。

有贊就曾使用過這種方式的變體，咱們依賴特定 ajax 庫的全局鉤子，解決了問題 2、3、4。但卻也帶來了其餘問題，好比對特定 ajax 庫的強依賴。

3. 聯調狀態判斷

我相信不少公司跟有贊同樣，聯調時間是在項目開始的時候開發預估的，開始聯調的時候前端其實並不知道後端接口是否真的OK了，或者說至少能調通了。因此經常會碰到的問題是，後端同窗告訴你能夠聯調後，你發現接口報的全是 404 或者 500 ，最後一查是後端環境配置有問題。

其實有贊在以前也並無找到一個比較好的方案，到如今也只能說還處於探索階段。

3、那麼到底什麼樣的協做方式是咱們想要的

1. 對於文檔來講

1. 後端同窗能快速生成文檔，而且持續維護。
2. 文檔須要包含足夠多的信息
3. 友好的接口定義展現

2. 對於數據 mock

1. 方便合做雙方可同時修改，即時生效
2. 最好能夠自動生成隨機返回值
3. 能根據不一樣的請求參數返回不一樣數據
4. 修改 mock 數據的行爲，能夠快速通知到合做方，避免雙方對數據格式認知不一樣步

3. 對於更好的判斷聯調時間

經過比較科學的方式判斷後端接口是否已經可被調用。

4、ZanApi 是如何作到的

首先，後端同窗在寫文檔這件事上，成本是否能夠爲零？

有贊目前在大力推動服務化，而且引入了 node 做爲中間層。因此在有贊，先後端的邊界變成了 browser + node -> java 服務化接口。

對於 java 同窗來講，業界已經一些比較成熟的方案來生成接口文檔，好比 swagger 、api blueprint 、swift。

但這些方案要麼須要 java 同窗引入不少非項目的三方依賴，要麼有它本身的一套接口定義方式從而增長 java 同窗的工做量。

並且有些方案並不適用於目前愈來愈主流的 browser & node -> 協議網關 -> java 服務化接口 這種先後端協做方式。

1. ZanApi 的文檔生成方案

1.1 解決快速生成、更新文檔的問題

爲了讓 java 同窗更方便的生成文檔，咱們爲 java 同窗提供了IDEA Intellij 插件。

最終的效果是，java 同窗可以一鍵生成、更新接口文檔。

1.2 解決文檔數據問題及展現

咱們在遠程部署了一個 java 解析服務器，經過該解析服務，咱們能夠將 java 代碼裏的備註抽取出來生成接口字段註釋。最終一個接口的返回值定義多是這樣的。

因此，若是 java 同窗自己有比較好的寫註釋的習慣，那麼對他來講生成一個合格的接口文檔將是零成本的。

2. ZanApi的數據 mock 方案

目前有贊完整的數據 mock 方案如圖所示：

從客戶端（pc / mobile）發起的請求在通過 ZanProxy 過濾後，將須要 mock 的接口打到 ZanApi 上，通過 ZanApi 返回 mock 數據。

2.1 解決可同時修改，快速通知的問題

因爲 ZanApi 部署在遠端，先後端可同時修改，因此自己自然沒有這個問題。

而且在 ZanApi 系統上，你能夠收到本身收藏的接口的 mock 數據變動通知，能夠較快的感知 mock 數據的變動。

2.2 支持多份 mock 數據，自動匹配

ZanApi 支持爲同一個接口添加多份 mock 數據，請求在數據 mock 時，ZanApi 能經過請求參數，自動返回不一樣 mock 數據。

2.3 支持根據接口定義返回隨機數據

當 java 同窗經過 Idea 插件 自動生成接口文檔時，ZanApi 會經過解析服務獲取接口的返回值定義並自動講定義轉化成 JSONSchema 格式。

當須要返回隨機數據時，ZanApi 能夠根據接口返回值的 JSONSchema 定義產生隨機數進而返回給客戶端。

3. ZanApi 對聯調的支持

在 ZanApi 上，你能夠爲每一個接口建立不一樣環境下的測試用例。在測試用例的基礎上，你能夠以項目維度建立一個接口集合。

當接口集合建立完畢後，ZanApi 提供了 一鍵測試 功能。

一鍵測試功能會獲取該接口集合內全部的接口，並將這些接口中定義的測試用例完整的跑一遍。若是其中某一個接口沒法調通，那麼 ZanApi 將提示你該接口測試失敗。

甚至，ZanApi 容許你經過對比真實接口返回值和接口返回值定義（或者對比以前已存在的某個 mock 數據）來判斷該接口是否符合預期。

好比，在接口的返回值定義中字段 count 是一個數字，可是 ZanApi 發現測試用例返回的真實數據中該字段是一個 string ，那麼該測試用例也將不會經過。

UI以下：

5、最後

在有贊技術開放日上介紹了 ZanApi 後發現你們對 ZanApi 仍是有着比較大的興趣。可是因爲咱們還沒有有時間整理開源相關的事宜，而且確實 ZanApi 還有不少不成熟的地方啊，因此 ZanApi 開源在短時間內應該沒辦法實現。可是咱們是有開源的打算的。

咱們但願在過一段時間 ZanApi 更成熟了，在有贊內部真正成爲了接口文檔事實標準的時候，再讓它跟你們見面。我相信到時候 ZanApi 必定會更好~