點擊上方“朱小廝的博客”，選擇“設(shè)為星標” 后臺回復(fù)"書"，獲取后臺回復(fù)“k8s”，可領(lǐng)取k8s資料

隨著微服務(wù)的越來越流行，越來的越多的公司開始實行微服務(wù)架構(gòu)，相對于單一應(yīng)用架構(gòu)，微服務(wù)將復(fù)雜性拆分并且打散到一個個粒度更加細分的應(yīng)用中，極大了減少了開發(fā)中單個服務(wù)的復(fù)雜性，開發(fā)人員只需要面向?qū)Ｗ我粯I(yè)務(wù)場景編程，從技術(shù)開發(fā)角度，單一服務(wù)代碼量上減少很多，從業(yè)務(wù)角度上，業(yè)務(wù)復(fù)雜性的降低降低了需求的溝通成本，然而，整體業(yè)務(wù)復(fù)雜性依然存在，當(dāng)我們需要接入或者依賴其他服務(wù)時，通常作為接入方來說，我們不需要深入了解服務(wù)提供方的業(yè)務(wù)，此時API成為了開發(fā)人員間的溝通語言。良好的API設(shè)計，能極大的減少溝通成本，甚至有時候可以代替文檔，尤其是對于基礎(chǔ)性服務(wù)來說，服務(wù)的可擴展性有時候體現(xiàn)在API的可擴展性，我曾經(jīng)參與過一個基礎(chǔ)業(yè)務(wù)微服務(wù)的業(yè)務(wù)升級，由于舊版本的API劃分不夠清晰，部分API存在重復(fù)性，后面不得不對大部分API進行重構(gòu)（替換為新版本的API），僅僅在服務(wù)消費方升級這個階段就持續(xù)1-2個月之久，在這個過程中也不斷對API設(shè)計中存在的一些問題以及應(yīng)該遵循哪些原則進行了一些思考。

API先行

在敏捷開發(fā)的大浪潮下，產(chǎn)品上通常要求快速迭代，面對一個新的需求，如果需要開發(fā)新的接口，通常在表結(jié)構(gòu)完成設(shè)計后，開發(fā)人員就需要完成API設(shè)計并交付消費方（即服務(wù)的調(diào)用方或者依賴方，文中其余部分均表示此含義），在技術(shù)聯(lián)調(diào)前，消費方可以Mock接口來完成調(diào)試。所以通常來說，API先與服務(wù)交付，之后再完成編碼，測試，調(diào)試等工作。當(dāng)然，由于可能在需求細節(jié)，技術(shù)實現(xiàn)方面可能在實現(xiàn)過程中發(fā)現(xiàn)需求需要調(diào)整，或者API接口的調(diào)整，最初版本的API可能是不成熟的，導(dǎo)致我們經(jīng)常在API調(diào)整或者演化過程中在API維護方面存在很多遺漏，所以API最初交付后的維護是持續(xù)性的工作。

API設(shè)計常見問題

在我們設(shè)計API過程中由于存在經(jīng)驗的缺失，或者由于多次交接，或者由于經(jīng)歷多次需求的變更，導(dǎo)致服務(wù)的API慢慢腐化，帶來以下常見的問題。

• 被遺忘的注釋，注釋通常描述了API的功能以及參數(shù)說明，以及如何接入，甚至給出簡單示例，過于詳細的注釋會帶來一定的反作用，例如因為新需求帶來了內(nèi)部邏輯的調(diào)整，但是由于未及時對API的注釋進行更新，會給新接入的調(diào)用方帶來潛在的風(fēng)險。所以不僅僅需要為API提供完整清晰的注釋，當(dāng)內(nèi)部邏輯變更時，作為開發(fā)人員通常也需要評估API層面的變更，包括注釋。

• 接口數(shù)量持續(xù)膨脹，有很多原因帶來接口數(shù)量的膨脹，可能是接口升級，但是舊接口無法直接下線，所以會提供一個功能類似的新接口；可能是新接管一個服務(wù)由于對業(yè)務(wù)不了解，面對新需求直接開發(fā)新接口；可能是接口分類劃分不合理，或者數(shù)據(jù)模型混亂導(dǎo)致API劃分混亂，出現(xiàn)API功能重復(fù)，最后導(dǎo)致一個場景多個API接口都可以滿足，這樣很明顯是應(yīng)該避免的。解決這些問題都需要建立在對業(yè)務(wù)充分理解的基礎(chǔ)上，下文的設(shè)計原則會針對這類問題給出解決方案。

• 缺乏有效測試，很多開發(fā)人員往往忽略對于接口的測試，無論是內(nèi)部邏輯細節(jié)的單元測試，還是接口層面的測試，都是服務(wù)健壯性的一個有效保證，如果無法對接口進行有效測試，不僅是不負責(zé)任的提現(xiàn)，而且還會經(jīng)常被線上bug困擾。

API設(shè)計的原則

簡單且專注

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

• • 按照業(yè)務(wù)主體劃分，不一樣的業(yè)務(wù)主體采用不一樣的接口類

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

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

良好的注釋

• 注釋應(yīng)該包含哪些；接口的使用場景，參數(shù)的說明，在接口類說明中可以給出接口文檔鏈接地址，方便調(diào)用方查看

• 參數(shù)的說明；包含參數(shù)代表的含義，參數(shù)的類型按照Javadoc link規(guī)范，參數(shù)是否為空，特殊值說明

• 過期說明；如果接口已經(jīng)過期，需要給出過期說明，對于 Java 來時就是@Deprecated注解，并給出切換接口說明，如果條件允許可以推動調(diào)用方進行接口遷移，后續(xù)對舊接口下線

擴展性

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

• 多參數(shù)結(jié)構(gòu)與單一參數(shù)類結(jié)構(gòu) 通常來說，如果一個接口的參數(shù)小于三個，那么建議使用多參數(shù)接口，這樣做到直觀簡潔 如果一個接口的參數(shù)較多而且后續(xù)可能經(jīng)常出現(xiàn)變動，為了便于擴展和兼容，會將參數(shù)封裝到一個類結(jié)構(gòu)中，記得同樣對每個字段給出完整的注釋說明。

• 類復(fù)用噩夢 在單一參數(shù)類結(jié)構(gòu)下，我經(jīng)?？吹蕉鄠€存在明顯功能差異的接口頻繁復(fù)用一個結(jié)構(gòu)體，甚至接口參數(shù)和返回值都復(fù)用一個DTO，為了保證兼容，又不得不在同一個DTO內(nèi)不斷加字段，久而久之維護成本持續(xù)增高，這是一種不合理的類設(shè)計，如果遵守專注原則，這個問題很多時候可以避免。

兼容性

• 接口邏輯或者參數(shù)變更時，需要對舊的接口保持兼容，這個是API變更時一定要遵守的原則之一，而且要通過接口測試來驗證兼容性。

• 是否要新增接口，當(dāng)面對一個新的需求時，為了避免對舊接口直接修改，有的開發(fā)人員會統(tǒng)一提供新的接口，如果并非邏輯上發(fā)生較大的變更，這樣做會提高API的維護成本，后續(xù)如果不對API進行重構(gòu)，新增加的維護成本將遠大于最開始節(jié)省的開發(fā)成本，例如需要對某個參數(shù)增加有效校驗，那么我們需要對兩個接口的API實現(xiàn)都做修改，而且是重復(fù)性的代碼，而且我們的影響范圍已經(jīng)成了兩個接口，這樣影響范圍的擴大也帶來了更多的潛在風(fēng)險。當(dāng)然在某些場景例如接口邏輯出現(xiàn)大的調(diào)整，API重構(gòu)等情況下，更好的方法是提供新的接口，并推動服務(wù)消費者使用新的API，最后慢慢下線舊的API，這樣才能遵循簡單和專注的原則。

完善的測試

• 單元測試，完善的單元測試能保證代碼的健壯性，提前在編碼階段發(fā)現(xiàn)并解決潛在的bug，單元測試是一個開發(fā)人員的必備能力。

• 接口和場景測試，接口測試包含內(nèi)部邏輯驗證，異常輸入，并發(fā)等場景下對單一接口的驗證，如果要對API進行完整的邏輯驗證，需要開發(fā)人員構(gòu)造完整的測試數(shù)據(jù)（通常包含scheme.sql和data.sql文件），尤其是對于基礎(chǔ)服務(wù)，需要對某些復(fù)雜業(yè)務(wù)場景下聯(lián)合多個接口完成某個場景的測試，并對中間的數(shù)據(jù)和輸出進行Assert確認，這樣也會代碼一定的測試代碼維護成本，需要開發(fā)人員進行利弊權(quán)衡。

重視文檔

良好的注釋和文檔能減少大部分和服務(wù)消費者的溝通工作，也避免了一些錯誤的接口調(diào)用。沒有人希望每次都需要在IM工具上浪費大量口水或者需要當(dāng)面詢問才知道如何正確使用API，也沒有開發(fā)者愿意每天重復(fù)回答如何調(diào)用提供的接口。對于接口文檔，可以是采用Javadoc這樣簡單的方式，也可以是通過wiki來集中管理，可以是markdown文檔，也有很多的開源系系統(tǒng)例如Swagger，yapi，eolinker等；微服務(wù)的架構(gòu)極大的加強了溝通的成本，這也是微服務(wù)架構(gòu)的一個弊端，但是合理的利用 工具 可以減少不必要的溝通。

總結(jié)

作為微服務(wù)之間的橋梁，API設(shè)計和維護是微服務(wù)架構(gòu)中很重要的一個環(huán)節(jié)，每個開發(fā)人員不僅僅需要良好的代碼規(guī)范，也需要建立并遵守API設(shè)計規(guī)范。API設(shè)計能力在微服務(wù)架構(gòu)中作為軟實力的一個部分，需要開發(fā)人員有一定的設(shè)計經(jīng)驗的積累，同時，只有不斷的思考和總結(jié)才能更加深入的理解。

想知道更多？掃描下面的二維碼關(guān)注我后臺回復(fù)"技術(shù)"，加入技術(shù)群后臺回復(fù)“k8s”，可領(lǐng)取k8s資料【精彩推薦】

• 原創(chuàng)|OpenAPI標準規(guī)范

• 中臺不是萬能藥，關(guān)于中臺的思考和嘗試
  

• ClickHouse到底是什么？為什么如此牛逼！

• 原來ElasticSearch還可以這么理解

• 面試官：InnoDB中一棵B+樹可以存放多少行數(shù)據(jù)？

• 微服務(wù)下如何解耦？對于已經(jīng)緊耦合下如何重構(gòu)？

• 如何構(gòu)建一套高性能、高可用、低成本的視頻處理系統(tǒng)？

• 架構(gòu)之道：分離業(yè)務(wù)邏輯和技術(shù)細節(jié)

• 星巴克不使用兩階段提交
  

點個贊+在看，少個 bug?????

總結(jié)

以上是生活随笔為你收集整理的微服务API设计的实践与思考总结的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。