Alan Tsai 的學習筆記


學而不思則罔,思而不學則殆,不思不學則“網貸” 記錄軟體開發的點點滴滴 著重於微軟技術、網頁開發、DevOps、C#, Asp .net Mvc、Azure、AI、Chatbot、Docker、Data Science

[apiary][01]設計API時好用的工具 - 讓前後端溝通格式不再卡卡 - 概念介紹篇

2019-03-24 星期日
[apiary]設計API時好用的工具 - 讓前後端溝通格式不再卡卡 - 概念介紹篇.jpg
圖片來源:https://pixabay.com/en/books-spine-colors-pastel-1099067/,logl來源:https://apiary.io/

近幾年前端爆炸式的成長,前後端分離的架構也越來越常見,如果前端和後端的開發者不是同一個人的時候,怎麽樣讓並行開發可以變得容易就非常的重用。

很長遇到一個問題是,前端開發者和後端開發者在API的内容以及格式有落差導致兩邊不好並行開發。

接下來的幾篇文章將要介紹Apiary這個工具,透過這個工具可以讓兩邊溝通沒有落差,並且可以同時進行開發。

這篇先從爲什麽選擇Apiary做開始,市面那麽多種,爲什麽要選Apiary,和其他方案比起來有什麽好處。

先從前後端開發問題看起,以及爲什麽Apiary (API Blueprint)是最適合的解決方案。

前後端分離開發遇到的問題,以及可能解決的方法

前後端分離不用説是最近開發比較常見的一種架構,由後端提供API服務讓前端去呼叫然後呈現内容。

這種框架的好壞不再這個系列的探討範圍,但是這種開發方式有一個很大的問題是:在開發過程中,怎麽確保前端和後端所知道的API定義都一樣?

這個問題可能有幾種處理方式:

  1. 前端和後端不同時開發
  2. 先定義好文件,前端和後端同時開發
  3. 用一些工具例如postman或者json server建立出mock server

不過這集中處理方式多多少少都有一些缺點,也因此了有這系列介紹apiary的文章。

在進入正題之前,先看看這些處理方式有什麽問題。

前端和後端不同時開發

第一種解決方式肯定是最直覺但是不一定有辦法運行的方法。

既然前端需要有等API,那麽何不等到後端開發好了前端在去接?

這種方式的好處是,因爲接的是正式API,接好了,那麽一切都好了。

但是,最大的問題是,沒辦法前後端同時開發。因爲前端一定要等後端開發好了才有辦法開始。

先定義好文件,前端和後端同時開發

第一種方式沒辦法同時開發是因爲不知道API長什麽樣子因此要等後端。

那麽是不是把API的格式定義好就可以同時開發了?

理論上可行,但是這個方式也有兩個問題:

  1. 文件用什麽格式定義 - 每個開發者撰寫是否會依照同樣格式,並且大家看到的理解是否不同
  2. 直到後端開發好了才知道有沒有問題 - 在開發過程,由於只有文件,沒辦法實際驗證,那麽前端到底寫對沒對完全看不出來

用一些工具例如postman或者json server建立出mock server

第二種方式看似前後端有了文件就可以同步開發,但是問題也不少。

最大的問題點是,前端沒辦法及時測試看看目前撰寫的和文件定義是否有不同。

因此又有了第三種,乾脆不寫文件了(或者除了文件之外),直接建立假的API Mock Server,前端就直接打Mock Server。那麽只要到時候真的Server和Mock server格式一樣,理論上只是切換api的host而已。

這種方式相較第二種好了許多,但是很大的問題變成:

  1. 修改Mock Server不一定容易 - 例如假設使用JSON Server,那麽撰寫的人需要熟悉npm的開發環境 - 學的確不難,但是如果作爲純後端要修改還需要一點時間上手
  2. 太過於依賴某個工具 - 例如使用的是postman,那麽要用postman的ui建立mock server,要版控這個文件定義就沒有辦法,並且只能夠用postman做修改

總結下來,上述各有優略,但是每一個工具想要解決的是:

  1. 前後端沒有統一格式,就沒辦法同時開發
  2. 文件沒有定義好的撰寫格式 - 每個人撰寫方式可能有點不同,怎麽確保大家寫出來的格式一樣
  3. 只有文件沒有mock server,還是要等後端好了才有辦法驗證前端是否沒寫好
  4. mock server撰寫方式不一致 - 沒辦法用自己習慣的方式撰寫mock server,有些會太過依賴某個工具

以上這些問題其實很常見,因此世界上已經有聰明人想出了解決方法,同大多數解決方法一樣,不止一種解決方案。

解決方案:從統一格式看起

文件化API是一第一步,有了文件化的API之後,就可以透過工具產生出Mock Server。

有了Mock Server之後,前後端的開發就可以同步進行,因爲前端可以用Mock Server邊開發邊驗證是否攥寫符合文件。

既然知道文件化API是第一步,那麽用一個定義好,開放格式變得非常重要。

目前市面上最廣汎使用的API文件格式有幾種:

  1. OpenAPI
  2. API Blueprint
  3. RAML

OpenAPIAPI BlueprintRAML
使用的格式YAML/JSONMarkdown (有些變化)JSON
最出名的工具SwaggerApiary
建議使用情景後端已經開發好 - 產生文件用新開發需求,前後端溝通用不建議使用
從上面總結的table可以看出,其實OpenAPI以及API Blueprint不一定要二擇一,而是不同時期,使用最適合的工具

如果對每個格式的細節有興趣,請繼續看,不然跳過即可。

OpenAPI

OpenAPI可能大家不熟悉,但是提到Swagger應該寫API的後端工程師都有聽説過。

簡單來説,Swagger可以讓我們從程式碼產生出API文件。而Swagger產生出來的就是OpenAPI的格式。

OpenAPI的格式為YAML/JSON,因此可以容易被版控。

API Blueprint

API Blueprint是另外一個撰寫API的格式,而使用API Blueprint最出名的工具就是Apiary

API Blueprint的格式為某種變形的Markdown,換句話説大家都會寫,相信不會寫markdown的工程師應該非常少數,並且版控容易。

但是相較於OpenAPI有Swagger可以從程式碼產生出來,API Blueprint就沒有。

RAML

RAML其實和OpenAPI定位有點想,使用的也是JSON的格式。

不過由於和OpenAPI的定位很類似,因此目前比較少人再用了。

以我個人而言,選擇API Blueprint作爲文件撰寫,因爲Markdown大家都會,並且直接看原始也都看得懂。

相較而言,OpenAPI則看起來沒有那麽的直覺,RAML又沒有OpenAPI那麽廣汎,那麽選RAML還不如選OpenAPI。


左邊是API Blueprint,右邊則是一樣的API用OpenAPI撰寫

Apiary是什麽?

上面説了那麽多,終於要進入了正題介紹這個系列的主軸,Apiary。

Apiary小檔案

  1. 官網:https://apiary.io/
  2. 免費方案允許建立無限個專案,並且最多5個人可以維護
  3. 免費方案允許有Mock Server

Apiary本質上是一個Editor+Mock+Test Server的服務,他不止支援API Blueprint,也支援OpenAPI的格式。

撰寫好的文件自動會提供Mock Server可以使用,因此前端可以直接打Mock Server就可以驗證撰寫的是否有問題。

對於後端,有提供Test服務,能夠驗證後端產生的API是否同文件一樣。

免費的版本支援5個人同時編輯一個檔案,因此小團隊共同編輯也沒有什麽問題。

chrome_2019-03-24_16-54-02.png
產生出來的文件樣子

結語

這篇介紹了從最原始的問題,到最後幾種不同解決方案的介紹,以及非常初步介紹Apiary這一個工具。

花了一整個篇幅介紹問題是因爲能夠讓大家理解,爲什麽花時間學習API Blueprint以及Apiary是很值得。

下一篇([apiary][02]設計API時好用的工具 - 讓前後端溝通格式不再卡卡 - 工具使用介紹篇)先從Apiary的基本使用介紹開始。


如果文章對您有幫助,就請我喝杯飲料吧
街口支付QR Code
街口支付QR Code
街口支付QR Code
支付寶QR Code
街口支付QR Code
微信支付QR Code
2019-03-24 星期日
comments powered by Disqus