随着微服務的越來越流行，越來的越多的公司開始實行微服務架構，相對于單一應用架構，微服務将複雜性拆分并且打散到一個個粒度更加細分的應用中，極大了減少了開發中單個服務的複雜性，開發人員隻需要面向專注單一業務場景程式設計，從技術開發角度，單一服務代碼量上減少很多，從業務角度上，業務複雜性的降低降低了需求的溝通成本，然而，整體業務複雜性依然存在，當我們需要接入或者依賴其他服務時，通常作為接入方來說，我們不需要深入了解服務提供方的業務，此時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設計能力在微服務架構中作為軟實力的一個部分，需要開發人員有一定的設計經驗的積累，同時，隻有不斷的思考和總結才能更加深入的了解。
是一個專注于程式員圈子的技術平台，你可以收獲逆鋒起筆
、最新技術動态
、最新内測資格
、BAT等大廠大佬的經驗
、增長自身
、學習資料
、職業路線
，微信搜尋賺錢思維
關注！逆鋒起筆