本文整理 API design-first 方法的挑戰。
(本文轉貼自分站:huanin.cc)
簡介
API design-first(設計優先)方法也稱為 contract-first(合約優先),指的是先設計 API,並以特定格式的語法寫成 API spec(規格),然後再由 developers 按照 API spec 來實作。
用來撰寫 API spec 的語法,目前看到比較受歡迎的是 OpenAPI(前身叫做 Swagger),而使用 OpenAPI 撰寫的規格,可以用一些現成工具(例如 SwaggerUI 或 Redoc)轉換成網頁形式的 API 參考手冊,相當方便。
相較於 design-first,另一種作法是 code-first,也就是先寫程式碼,不過通常還是會有一些不那麼正規嚴謹的需求分析與設計文件。而且,採用 code-first 方法的團隊也可以用工具產生 API 參考手冊,做法是在程式碼當中寫一些特定的標註(annotations)或註解,然後用工具讀取程式碼檔案來產生 OpenAPI spec 檔案,最後再轉換成 API 參考手冊。
採用 design-first 的團隊,其最終產生的 API 參考手冊的品質主要是由撰寫 API spec 的 designer 決定。另一方面,code-first 團隊所產生的 API 參考手冊則仰賴 developer 的辛勞。
接下來只談 design-first 方法可能遭遇的挑戰,其中有一些是來自我的工作觀察。
Design-first 實施要點
當有人對 API 的用法提出這類疑問:「A 和 B 哪個才是對的?」此時應該去查看 API spec。以 spec 為準。
如此一來,有疑義時,只要看 API spec 即可,不用非得去看程式碼或跑一些測試來確認。因此,採用 API design-first 方法時,團隊成員都要認同 API spec 是 single source of truth,這點至關重要。
幾個重點:
- 使用者手冊或教學文件有時會落後、寫錯、或遺漏一些細節,但採用 design-first 方法時,API spec 應該是最正確而且完整的參考依據。
- 當 developer 按照 API spec 來寫程式的時候,若碰到規格方面的問題,一定要將問題反映給 API designer 知道,以便更新 spec。如果只修改程式碼而沒有同步更新 API spec,將造成日後生成的 API 參考手冊與 API 實際行為不符,令使用者困惑。
- 一旦 API 與實作的程式碼有新的變動,必須要有管道能讓相關人員(stakeholders)也知道 API 有哪些變動。
Design-first 的挑戰
挑戰一:完成多少設計才開始實作?
若花太少時間在 API design,未來可能要付出更大心力來修改 API spec 和程式碼。若花太多時間 design,則會令實作較晚起步,可能耽誤開發時程。
故只能盡量試著平衡,並理解:design 不可能一次到位,但相較於實作完成後再回頭反覆修改,在設計階段解決問題的成本還是比較低。
挑戰二:當 API spec 變動時,如何把這些變動有效傳遞給相關人員知道?
前面提過,developer 實作 API 時若發現 spec 有問題,一定要反映給 designer 知道,以便設計與實作保持一致。除此之外,當 spec 有變動時,還有其他相關人員可能也需要知道,例如 PM 和 Technical Writer(沒錯,寫這篇筆記也是我替自己發聲 XD)。
比較好的做法,是制定一個標準的變動程序,包括如何提出變更、接受變更,以及發布變更。
結語
這篇筆記的重點在於組織內的訊息溝通,亦即如何避免有人漏接相關資訊,以確保 API 的設計、實作、和相關文件都能始終維持一致。以我看到的情形來說,這還真不容易做到。
Conway 定律:軟體系統的結構會反映組織的內部溝通結構。
確實如此。
Reference
- Designing APIs with Swagger and OpenAPI by by Joshua S. Ponelat and Lukas L. Rosenstock
沒有留言: