[[416245]]

• API先行
• API設計常見問題
• API設計的原則
• 簡單且專注
• 良好的注釋
• 擴展性
• 兼容性
• 完善的測試
• 重視文檔
• 總結

隨著微服務的越來越流行，越來的越多的公司開始實行微服務架構，相對于單一應用架構，微服務將復雜性拆分并且打散到一個個粒度更加細分的應用中，極大了減少了開發中單個服務的復雜性，開發人員只需要面向專注單一業務場景編程，從技術開發角度，單一服務代碼量上減少很多，從業務角度上，業務復雜性的降低降低了需求的溝通成本，然而，整體業務復雜性依然存在，當我們需要接入或者依賴其他服務時，通常作為接入方來說，我們不需要深入了解服務提供方的業務，此時API成為了開發人員間的溝通語言。

良好的API設計，能極大的減少溝通成本，甚至有時候可以代替文檔，尤其是對于基礎性服務來說，服務的可擴展性有時候體現在API的可擴展性，我曾經參與過一個基礎業務微服務的業務升級，由于舊版本的API劃分不夠清晰，部分API存在重復性，后面不得不對大部分API進行重構（替換為新版本的API），僅僅在服務消費方升級這個階段就持續1-2個月之久，在這個過程中也不斷對API設計中存在的一些問題以及應該遵循哪些原則進行了一些思考。

API先行

在敏捷開發的大浪潮下，產品上通常要求快速迭代，面對一個新的需求，如果需要開發新的接口，通常在表結構完成設計后，開發人員就需要完成API設計并交付消費方（即服務的調用方或者依賴方，文中其余部分均表示此含義），在技術聯調前，消費方可以Mock接口來完成調試。所以通常來說，API先與服務交付，之后再完成編碼，測試，調試等工作。

當然，由于可能在需求細節，技術實現方面可能在實現過程中發現需求需要調整，或者API接口的調整，最初版本的API可能是不成熟的，導致我們經常在API調整或者演化過程中在API維護方面存在很多遺漏，所以API最初交付后的維護是持續性的工作。

API設計常見問題

在我們設計API過程中由于存在經驗的缺失，或者由于多次交接，或者由于經歷多次需求的變更，導致服務的API慢慢腐化，帶來以下常見的問題。

• 被遺忘的注釋，注釋通常描述了API的功能以及參數說明，以及如何接入，甚至給出簡單示例，過于詳細的注釋會帶來一定的反作用，例如因為新需求帶來了內部邏輯的調整，但是由于未及時對API的注釋進行更新，會給新接入的調用方帶來潛在的風險。所以不僅僅需要為API提供完整清晰的注釋，當內部邏輯變更時，作為開發人員通常也需要評估API層面的變更，包括注釋。
• 接口數量持續膨脹，有很多原因帶來接口數量的膨脹，可能是接口升級，但是舊接口無法直接下線，所以會提供一個功能類似的新接口；可能是新接管一個服務由于對業務不了解，面對新需求直接開發新接口；可能是接口分類劃分不合理，或者數據模型混亂導致API劃分混亂，出現API功能重復，最后導致一個場景多個API接口都可以滿足，這樣很明顯是應該避免的。解決這些問題都需要建立在對業務充分理解的基礎上，下文的設計原則會針對這類問題給出解決方案。
• 缺乏有效測試，很多開發人員往往忽略對于接口的測試，無論是內部邏輯細節的單元測試，還是接口層面的測試，都是服務健壯性的一個有效保證，如果無法對接口進行有效測試，不僅是不負責任的提現，而且還會經常被線上bug困擾。

API設計的原則

簡單且專注

• 簡單：在面向對象設計原則中，第一條是單一職責原則，同樣適用于API設計，我們的主體對象就是業務模型，API就是封裝內部邏輯后對外界開放的功能。保證API的簡單和職責單一，能夠避免解決上文中提到的接口數量膨脹問題。那如何才能實現API職責單一，需要我們在定義接口時能夠準確識別出接口之間的關聯性和邊界，對于API如何劃分可以通過以下角度：

  • 按照業務主體劃分，不一樣的業務主體采用不一樣的接口類
  • 查詢類和修改類的接口分離；通常來說我們對于數據的查詢場景遠大于修改的場景，而且查詢有多種多樣的業務場景，對于數據的修改請求通常來源于業務后臺人員對數據進行修改，此時的業務邏輯也通常會更加特殊（例如有很多額外數據校驗），所以建議修改類和查詢類API盡量分離，甚至可以將業務配置后臺類查詢和普通業務查詢分離以至于能夠適應各自的業務變更。

• 專注：一個單一接口的場景是基于業務抽象后專注于某一個場景并且互相不重合的，這樣才能保證接口的粒度足夠小，尤其是對于基礎類服務，接口粒度的劃分能保證接口是純粹的且互相獨立的，這樣才不至于在需求變化是涉及過多接口的變動（除非是對業務模型有較大的調整），另外要說明的是，內部邏輯的業務數據模型（POJO類）和API數據模型（DTO）有時候出現差異，否則可能需要消費者理解服務的業務模型才能正確的使用接口，這就要求在API設計中開發人員需要明確應該提供哪些數據模型給消費者，在此前提下更加有助于我們保證單一接口的專注。

良好的注釋

• 注釋應該包含哪些；接口的使用場景，參數的說明，在接口類說明中可以給出接口文檔鏈接地址，方便調用方查看
• 參數的說明；包含參數代表的含義，參數的類型按照Javadoc link規范，參數是否為空，特殊值說明
• 過期說明；如果接口已經過期，需要給出過期說明，對于 Java 來時就是@Deprecated注解，并給出切換接口說明，如果條件允許可以推動調用方進行接口遷移，后續對舊接口下線

擴展性

唯一不變的是變化，接口也會一直演化，我們不提倡過度提前設計，但是在演化過程中要始終保持接口的可擴展性。

• 多參數結構與單一參數類結構 通常來說，如果一個接口的參數小于三個，那么建議使用多參數接口，這樣做到直觀簡潔 如果一個接口的參數較多而且后續可能經常出現變動，為了便于擴展和兼容，會將參數封裝到一個類結構中，記得同樣對每個字段給出完整的注釋說明。
• 類復用噩夢 在單一參數類結構下，我經常看到多個存在明顯功能差異的接口頻繁復用一個結構體，甚至接口參數和返回值都復用一個DTO，為了保證兼容，又不得不在同一個DTO內不斷加字段，久而久之維護成本持續增高，這是一種不合理的類設計，如果遵守專注原則，這個問題很多時候可以避免。

兼容性

• 接口邏輯或者參數變更時，需要對舊的接口保持兼容，這個是API變更時一定要遵守的原則之一，而且要通過接口測試來驗證兼容性。
• 是否要新增接口，當面對一個新的需求時，為了避免對舊接口直接修改，有的開發人員會統一提供新的接口，如果并非邏輯上發生較大的變更，這樣做會提高API的維護成本，后續如果不對API進行重構，新增加的維護成本將遠大于最開始節省的開發成本，例如需要對某個參數增加有效校驗，那么我們需要對兩個接口的API實現都做修改，而且是重復性的代碼，而且我們的影響范圍已經成了兩個接口，這樣影響范圍的擴大也帶來了更多的潛在風險。當然在某些場景例如接口邏輯出現大的調整，API重構等情況下，更好的方法是提供新的接口，并推動服務消費者使用新的API，最后慢慢下線舊的API，這樣才能遵循簡單和專注的原則。

完善的測試

• 單元測試，完善的單元測試能保證代碼的健壯性，提前在編碼階段發現并解決潛在的bug，單元測試是一個開發人員的必備能力。
• 接口和場景測試，接口測試包含內部邏輯驗證，異常輸入，并發等場景下對單一接口的驗證，如果要對API進行完整的邏輯驗證，需要開發人員構造完整的測試數據（通常包含scheme.sql和data.sql文件），尤其是對于基礎服務，需要對某些復雜業務場景下聯合多個接口完成某個場景的測試，并對中間的數據和輸出進行Assert確認，這樣也會代碼一定的測試代碼維護成本，需要開發人員進行利弊權衡。

重視文檔

良好的注釋和文檔能減少大部分和服務消費者的溝通工作，也避免了一些錯誤的接口調使用。沒有人希望每次都需要在IM工具上浪費大量口水或者需要當面詢問才知道如何正確使用API，也沒有開發者愿意每天重復回答如何調用提供的接口。

對于接口文檔，可以是采用Javadoc這樣簡單的方式，也可以是通過wiki來集中管理，可以是markdown文檔，也有很多的開源系系統例如Swagger，yapi，eolinker等；微服務的架構極大的加強了溝通的成本，這也是微服務架構的一個弊端，但是合理的利用 工具 可以減少不必要的溝通。

總結

作為微服務之間的橋梁，API設計和維護是微服務架構中很重要的一個環節，每個開發人員不僅僅需要良好的代碼規范，也需要建立并遵守API設計規范。API設計能力在微服務架構中作為軟實力的一個部分，需要開發人員有一定的設計經驗的積累，同時，只有不斷的思考和總結才能更加深入的理解。