架構師觀點 - API First 的開發策略
摘要提示
- API First: 以 API 規格為開發首要，先定義合約再實作，將 domain 問題置於流程中心
- 長期目標與敏捷: 快速交付與回饋不等於忽略長期架構，需以 API 設計鎖定穩定核心
- 架構師角色: 在敏捷中負責抽象化與設計「公式」(核心機制)，維繫長期一致性與跨團隊協作
- 康威定律: 組織溝通型態映射系統結構，API 規格即團隊協作介面，影響分工與架構邊界
- API 與產品分界: API 輕、APP 重應用；用 SDK/BFF/模板降前端門檻，避免過度把複雜度塞入 API
- API 經濟: 標準化帶來自動化與規模化，進而形成生態系，成為商業增長引擎
- DX 與 UX 順序: 先顧開發者體驗(DX)再顧使用者體驗(UX)，以便擴大內外部開發動能
- 合約驅動流程: 以 OpenAPI/gRPC/IDL 等可驗證合約落地「先對齊、再開發、並行交付」
- 反模式警示: 只優化命名/安全/規範而忽略 domain 抽象，會得到「完美但無用」的 API
- 能力與文化: 以讀書會/制度化學習導入治理與設計模式，提升團隊 API 設計與管理成熟度
全文重點
本文源自作者於 DevOpsDays Taipei 2022 的 Keynote，聚焦於「API First」的開發策略，主張在整體開發流程中應先以 API 規格（interface/contract）為核心，將 domain 問題抽象為對外一致的通訊介面，藉此改變設計與協作模式。文章指出，多數團隊已理解 API 的重要性，但真正的關鍵在「First」：即在任何程式碼實作前，先釐清並凍結 API 結構，因為它關乎跨系統及跨團隊的長期穩定性與兼容性，不能頻繁大改。API 的「結構」決定使用方式，參數規格才是細節，故結構正確性最影響價值。
作者從三個面向檢視團隊對 API First 的「期待」與成熟度：產品面（先 DX 再 UX）、技術面（先合約後並行開發）、經營面（將 API 當產品與商業模式）。藉此提醒：若團隊仍偏向「先做應用、後補 API」，或把 API 當附屬，將難以發揮標準化帶來的規模紅利。延伸到組織層面，康威定律使 API 規格成為團隊協作的「合約」與邊界：規格糟、卻無法優化，往往是組織分工問題，而非單純技術議題。AWS 早於 2002 年便以內部備忘錄規範團隊必須以 API 為唯一溝通渠道（不得共享資料庫等），促成後續雲端服務與平台化的能力沉澱，說明 API First 的戰略性。
在敏捷語境下，短周期的交付與回饋，易忽略長期架構與非功能需求。此時，架構師的價值在於看見需求背後的共性，進行恰當抽象，設計可長期演進的「核心機制」（作者稱「設計公式」），再以穩定的介面（API spec）向團隊清楚傳達，並提供 SDK、框架、BFF 等降低使用門檻的工具，支持多團隊並行開發。以作者「折扣規則」案例為例：先定義購物車為統一的計算輸入與輸出協定，計算引擎成為核心機制，UI 與規則可快速擴展與替換，達到高內聚、低耦合、易測試與可持續優化。這種以核心機制驅動 API 定義的模式，使 API 能長期保持介面穩定、內部實作自由演進，避免版本爆炸與破壞性變更。
在產品與 API 的邊界拿捏上，作者主張 API 盡量精簡通用，避免將應用流程與 UI 細節固化到 API；要提升好用性可另以 SDK/BFF/範本補位。隨著規模擴大，組織會走向「M 型」：一端是越來越專精的 API/平台團隊，一端是門檻下降的應用/組裝團隊（含低代碼/無代碼），需以治理、工具與文化平衡模組化與客製化的光譜，避免過度設計或過度客製。從經營角度，API 標準化是自動化與整合的前提，能擴大到生態系，帶來新客群與新應用，類比樂高：高品質標準件+少量相容特件+組裝說明/工具，既能規模化又能快速客製。
推動 API First 需要文化與能力的同步升級：明確動機、建立合約驅動流程、導入可驗證規格（OpenAPI/gRPC/IDL/JSON Schema 等）、建立測試與相容性策略、規劃版本與治理，並以讀書會等制度化學習導入外部最佳實務。作者推薦三本關鍵書籍：Continuous API Management（治理與生命週期）、API Design Patterns（介面設計模式與一致性）、Software Engineering at Google（文化與工程決策）。最後小結指出：本文為系列第一部分，聚焦觀念與驅動力，下一篇將談合約優先的具體流程、從狀態機出發的 API 規格設計，以及案例與實作細節。
段落重點
寫在前面
作者以部落格補完 Keynote 未及內容，強調 API First 的關鍵在「First」而非「API」。開發應先把 API 視為對外合約，明確定義結構與規格，再展開實作，這雖似瀑布順序，實則逼迫團隊直面 domain 與 business 問題，避免以技術細節取代問題本質。作者提出本文結構：先談期待與動機、略過治理細節、深入開發策略（流程、設計、安全、避免過度設計）、補充案例與總結；並說明簡報與文字的互補，以及將「架構師在敏捷團隊中的角色」擴寫於文中，鋪陳後續從觀念到方法的完整論述。
1, 你的團隊有多「期待」推行 API First
作者以三個面向提問自我檢視：產品面（先 UI 還是 API）、技術面（先可運作還是先合約並行）、經營面（API 附屬還是產品）。右側答案越 API 導向。強調：先顧 DX 再顧 UX，是次序非取捨；API 規格即團隊溝通合約，牽動組織分工與架構演進。引用 API-First Approach 指出：以合約起手能在寫任何程式前與利害關係人對齊並快速迭代。提醒反模式：若只關注命名/規範/安全等外在一致性，而不以 domain 抽象為中心，將得到「完美但無效用」的 API。成功關鍵在於以 API 凝聚資源優先驗證 domain 設計，後文將以方法與案例示範。
1.1, 了解團隊現在的狀態
依三個提問校準現況：產品成熟度、團隊能力、競爭與策略都影響選擇。若走 API First，建議：1) 先 DX 再 UX，確保用 API 的開發者有好體驗以放大後續產出；2) 以 API 規格作為跨系統合約，對齊組織分工（康威定律），當規格難優化時，問題多在組織邊界非技術本身；3) 聚焦 API 作為唯一溝通管道，明確規格落地為技術合約（OpenAPI、gRPC IDL、JSON Schema、語言層 interface），並建立驗證雙方遵守合約的機制。作者亦反問：為何微服務成為趨勢？除技術外，還因它較貼合大規模團隊分工的維度。
1.2, 老闆期待的 API 經濟
從經營視角，API First 的價值在標準化→自動化→整合→規模化→生態系。API 將公司有價值的服務封裝為標準取得方式，擴大客戶內嵌與跨廠商整合，帶來新客群與應用。作者以樂高比喻：製造品質（程式品質）、設計品質（抽象與規格擴充性）、降低門檻（主題包、組裝指南=SDK/模板/BFF）三者合一，達到規模化與快速客製的平衡。進軍新領域（如從零售到餐飲）需在標準化基礎上加少量相容特件（API 擴充），以 API 收斂服務，外圍再組裝，兼顧不同情境。最後提醒 API 與 APP 分界：API 要精簡、避免綁定應用流程；讓好用性交給 SDK/BFF/範本，才能維持可重用與跨域延展。
1.3, 架構師在敏捷團隊該扮演的角色
敏捷/DevOps 強調快速交付與回饋，易忽略不緊急但重要的長期目標（架構、技術債、API 設計）。架構師需維繫長期視野：理解長期 road map（技術與領域）、協調多團隊/多程式碼庫、平衡可見需求與不可見風險、管理技術債。其核心能力是「抽象化」，設計能承載多變需求的「核心機制」（設計公式），再以穩定 API 介面對外，並提供工具支援開發者。以折扣計算案例示範：統一以購物車作為計算 input/output 的協定，計算引擎作核心，規則/UI 可快速擴展，測試與優化更容易。好 API spec 應長期穩定，必要變更需前向相容；成功關鍵是抽象是否對準 domain 核心。對於架構師在 Scrum 的定位，依產品性質與團隊能力可扮演 PO/顧問/Stakeholder/QA 等，但首要任務是塑造敏捷文化、幫助組織持續交付高商業價值。
1.4, 改變團隊的文化與能力
推動 API First 需同時調整文化與能力。除了以動機驅動改變（看見 API 經濟與規模效益），還要透過制度化學習與讀書會強化治理與介面設計能力。作者推薦三本書：1) Continuous API Management（治理/生命週期/版本/角色分工，將 API 當產品經營）；2) API Design Patterns（命名、資源階層、資料型別、方法、長執行作業、批次、分頁、篩選、安全/相容/重試等 30 個模式，建立一致介面）；3) Software Engineering at Google（文化、知識共享、工程決策的高標準與影響力）。建議先讀設計模式再讀治理，以「合約可驗證、介面一致、治理持續」三軸並進，逐步提升 API 團隊成熟度。
第一部分小結
本文作為系列第一篇，釐清 API First 的動機、價值與組織影響：以 API 合約為核心，對齊 domain 抽象與長期架構；以康威定律檢視組織與規格之間的互動；以架構師驅動抽象與核心機制設計，並以 SDK/BFF/工具降低落地門檻；以治理與設計模式的系統化學習提高成熟度。第二部分將探討合約優先的實務流程、從狀態機出發的 API 規格設計、以及案例與故事，補足從理念到落地的方法鏈。文末附上演講連結與直播錄影，提供多元學習管道，呼應作者主張以文字沉澱觀點、以合約鞏固協作、以抽象驅動長期演進。
資訊整理
知識架構圖
- 前置知識：
- API 基礎（HTTP、REST、狀態碼、Request/Response）
- 介面/契約觀念（OpenAPI/Swagger、gRPC IDL、JSON Schema）
- 軟體工程基礎（OOP、抽象化、TDD、持續交付/DevOps、Scrum）
- 架構與組織（微服務、康威定律、API/APP 分界）
- 產品與體驗（DX 與 UX 的關係、API 經濟與生態系）
- 核心概念：
- API First：在流程最前面確定 API 規格（契約），一切以契約為準
- 契約先行與回饋循環：先訂介面再寫程式，早期驗證與利害關係人回饋
- Domain 抽象化與結構設計：用核心機制/狀態機驅動 API 結構，介面長期穩定
- 架構師在敏捷中的角色：維護長期目標，抽象化與設計公式，跨團隊對齊
- 標準化到規模化（API 經濟）：以標準 API 整合→自動化→生態系
- 技術依賴：
- 規格層：OpenAPI / gRPC IDL / JSON Schema（契約作為唯一真相）
- 實作層：API Mock/Contract Test/Codegen → 平行開發（App 與 API）
- 架構層：微服務通訊（REST/gRPC）→ BFF/SDK 降低前端複雜度
- 流程層：CI/CD + 契約測試 + 版本相容策略（SemVer/後向相容）
- 治理層：API 生命週期管理（設計→發布→監控→版本化→退場）
- 安全層：左移安全（認證/授權、輸入驗證、Idempotency、重試/去重）
- 應用場景：
- 內外部系統整合（客戶/合作夥伴以 API 接入）
- 多團隊協作與微服務拆分（以 API 為唯一溝通介面）
- 產品跨領域延伸（零售能力重組到餐飲等場景）
- 高併發/高流量服務的產品化與生態系經營
- 建立 API 園林（多產品線 API 的治理與版本演進）
學習路徑建議
- 入門者路徑：
- 打好 HTTP/REST 基礎，理解 DX/UX 與 API First 的關係
- 以小案例撰寫 OpenAPI，練習從契約產生 Mock 與客戶端
- 閱讀 API Design Patterns 的 Introduction/Design Principles 章節
- 練習分頁、過濾、版本等基本設計模式
- 進階者路徑：
- 練習以 Domain 抽象化設計 API 結構與狀態機
- 設計 API/APP 邊界，導入 BFF/SDK 與契約測試
- 研讀 Continuous API Management，建立 API 生命周期與治理觀念
- 在團隊導入設計審查（Design Review）與契約評審（Contract Review）
- 實戰路徑：
- 導入 Contract-First 的開發流程：契約→Mock/Tests→平行實作
- 在 CI/CD 納入契約相容檢查、API Lint、安全與回歸測試
- 設定唯一通訊規範（禁共用資料庫），落地 Bezos memo 式原則
- 建立 API 產品化策略（版本/相容、文件/DX、SDK、去客製化的擴展點）
- 用案例推動文化變革（讀書會/設計工作坊/設計指引）
關鍵要點清單
- API First 定義：在任何程式碼前，先把 API 規格定義完整並作為唯一依據（契約） (優先級: 高)
- 契約先行的回饋：以 API 契約與 Stakeholders 早期對齊、獲取回饋、降低返工 (優先級: 高)
- Domain 抽象化與核心機制：用抽象化找出「設計公式/核心機制」，讓介面長期穩定 (優先級: 高)
- 架構師在敏捷中的角色：維護長期目標、跨團隊對齊、設計與溝通架構 (優先級: 高)
- 康威定律與組織設計：API 介面即團隊協作介面，先設組織/邊界再穩定架構 (優先級: 高)
- DX 優先順序：先顧好開發者體驗（文件、範例、SDK、錯誤訊息）再擴 UX (優先級: 中)
- API/APP 邊界與減複雜：API 盡量精簡，以 BFF/SDK/模板承接複雜組合 (優先級: 高)
- 標準化→規模化→生態系：API 是整合與自動化的基礎，承接 API 經濟 (優先級: 中)
- 反模式：只追規範不解 Domain：介面再「漂亮」也無法創造商業價值 (優先級: 高)
- 版本與相容性：偏好後向相容與 SemVer，必要時提供並行版本與退場機制 (優先級: 高)
- 安全性左移：在設計階段考慮認證/授權、輸入驗證、Idempotency/重試/去重 (優先級: 高)
- 通訊唯一性原則：跨團隊只允許以 API 溝通，禁止共用資料庫等捷徑 (優先級: 高)
- 設計模式運用：分頁、過濾、批次、長任務、資源關係、多型等模式選用 (優先級: 中)
- API 治理與園林：以產品思維管理 API 生命週期、版本、文件、可觀測性 (優先級: 中)
- 模組化與客製化光譜：避免過度設計，按業務成熟度選擇擴展點 (優先級: 中)
- 文化與能力建設：讀書會/工作坊/設計審查，持續提升抽象化與設計能力 (優先級: 中)
