Alan Tsai 的學習筆記


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

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

2019-03-24 Sunday
[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
台灣 Pay QR Code
台灣 Pay QR Code
Line Pay 一卡通 QR Code
Line Pay 一卡通 QR Code
街口支付QR Code
支付寶QR Code
街口支付QR Code
微信支付QR Code
2019-03-24 Sunday
comments powered by Disqus