本文整理 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
沒有留言: