API先行
在敏捷開發的大浪潮下，產品上通常要求快速迭代，面對一個新的需求，如果需要開發新的介面，通常在表結構完成設計后，開發人員就需要完成API設計并交付消費方（即服務的呼叫方或者依賴方，文中其余部分均表示此含義），在技術聯調前，消費方可以Mock介面來完成除錯，所以通常來說，API先與服務交付，之后再完成編碼，測驗，除錯等作業，當然，由于可能在需求細節，技術實作方面可能在實作程序中發現需求需要調整，或者API介面的調整，最初版本的API可能是不成熟的，導致我們經常在API調整或者演化程序中在API維護方面存在很多遺漏，所以API最初交付后的維護是持續性的作業，
API設計常見問題
在我們設計API程序中由于存在經驗的缺失，或者由于多次交接，或者由于經歷多次需求的變更，導致服務的API慢慢腐化，帶來以下常見的問題，
? 被遺忘的注釋，注釋通常描述了API的功能以及引數說明，以及如何接入，甚至給出簡單示例，過于詳細的注釋會帶來一定的反作用，例如因為新需求帶來了內部邏輯的調整，但是由于未及時對API的注釋進行更新，會給新接入的呼叫方帶來潛在的風險，所以不僅僅需要為API提供完整清晰的注釋，當內部邏輯變更時，作為開發人員通常也需要評估API層面的變更，包括注釋，
? 介面數量持續膨脹，有很多原因帶來介面數量的膨脹，可能是介面升級，但是舊介面無法直接下線，所以會提供一個功能類似的新介面；可能是新接管一個服務由于對業務不了解，面對新需求直接開發新介面；可能是介面分類劃分不合理，或者資料模型混亂導致API劃分混亂，出現API功能重復，最后導致一個場景多個API介面都可以滿足，這樣很明顯是應該避免的，解決這些問題都需要建立在對業務充分理解的基礎上，下文的設計原則會針對這類問題給出解決方案，
? 缺乏有效測驗，很多開發人員往往忽略對于介面的測驗，無論是內部邏輯細節的單元測驗，還是介面層面的測驗，都是服務健壯性的一個有效保證，如果無法對介面進行有效測驗，不僅是不負責任的提現，而且還會經常被線上bug困擾，
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工具能提高作業效率相信大多數人都不會反對，國外的Postman，Swagger，國內的Eolinker，都是現在蠻多同行在用的API工具，
總結
作為微服務之間的橋梁，API設計和維護是微服務架構中很重要的一個環節，每個開發人員不僅僅需要良好的代碼規范，也需要建立并遵守API設計規范，API設計能力在微服務架構中作為軟實力的一個部分，需要開發人員有一定的設計經驗的積累，同時，只有不斷的思考和總結才能更加深入的理解，
來源：www.eolinker.com
轉載請註明出處，本文鏈接：https://www.uj5u.com/qita/264098.html
標籤：其他
下一篇：軟體測驗實體（一）