- 你是否也感同身受?
- 優秀API的特質
- API 設計原則
你是否也感同身受?
-
對接XX業務時,XX業務具備的功能和API全靠跑業務負責人那反覆逐個詢問、確認。用哪個API;怎麼用;有沒有限制;等等
-
各個業務間,甚至同一業務內,API風格不統一。
- API命名:按自然語義全翻譯的;按屬性角度定義的;按操作角度定義的;動賓、非動賓的;複數、非複數的;等等
- API入參:帶Map的;相同語義字段名稱不一樣;
- API出參:有包裝Resoponse的;直接返回結果數據的;相同數據,返回格式和字段名稱有差別的;
- 錯誤信息:直接返回中文提示的;返回提示信息編碼的;返回異常類型的;等等
-
XX業務API性能方面未知。
-
隨着業務的演進,開放的API持續在增加,但類同的很多
API編碼規範迫在眉睫
基於 Spring Boot + MyBatis Plus + Vue & Element 實現的後臺管理系統 + 用戶小程序,支持 RBAC 動態權限、多租戶、數據權限、工作流、三方登錄、支付、短信、商城等功能。
項目地址:https://github.com/YunaiV/ruoyi-vue-pro
優秀API的特質
自解釋
- 從API本身一眼就能看懂API是幹什麼的,支持的用法,適用的場景,異常的處理等
易學習
- 有完善的文檔,以及提供儘可能多的示例和可copy-paste的代碼。
易使用
- 功能強大,但使用簡單。不增加調用方的使用成本(例如要求業務方用API時需要額外的配置和依賴),不暴露覆雜的細節、冗長的使用流程給調用方感知。調用方只做最小的感知和最少的傳參。
難誤用
- 優秀的API可以使有經驗的開發直接使用API而不需要閱讀文檔。
- 充分的靜態檢查、動態校驗、顯式的異常說明、有效的錯誤提示。
基於微服務的思想,構建在 B2C 電商場景下的項目實戰。核心技術棧,是 Spring Boot + Dubbo 。未來,會重構成 Spring Cloud Alibaba 。
項目地址:https://github.com/YunaiV/onemall
API 設計原則
1. 充分原則
不是隨便一個功能就要有個接口,也不是隨便一個需求就要加個接口。
每新建一個接口,要有充分的理由和考慮,即這個接口的存在是十分有意義和價值的。無意義的接口不僅增加了維護的難度,更重要是對於程序的可控性的大大降低,接口也會十分臃腫。
2. 單一視角原則
設計接口時,分析的角度要統一。否則會造成接口結構的混亂。例如:不要一會以角色的角度設計,一會兒就要以功能的角度設計。
推薦:以"屬性對象 + 行爲"的視角定義API
3. 單一功能原則
每個API接口應該只專注一件事,並做好。產品概念簡單、關係清楚。功能模棱兩可,諸多特殊邏輯的API肯定不是個優雅的API,且會造成功能類似重複的API。
注:如果API它很難命名,那麼這或許是個不好的徵兆,好的名稱可以驅動開發、並且只需拆分與合併模塊即可。
功能大而全的API在靈活性、簡單性方面肯定捉襟見肘。定義API的粒度之前,建議先將業務分領域、劃邊界,以此來提取業務對象,然後再根據業務對象用例來設計單一功能的API。
比如:查詢會員,可能除了查詢會員表外還要獲取該會員的其他必要信息,但不要在查詢會員的同時還有修改權限等類似的其他業務功能,應該分成兩個接口執行。
4. 簡單原則
接口設計簡單、清晰。API執行的功能可以很豐富、很強大,但API聲明和用法一定要儘量的簡單,不能將功能的豐富通過複雜的用法來實現,這會導致API功能不單一,演進不可控。
最終的評審要看API的簡單易用程度。
- 你寫的例子,能不能讓你的代碼看起來更簡單?
- 你是不是強迫調用方關注/提供他們不在乎的選項/配置?
- 有沒有毫無價值的額外步驟?
編寫的代碼一定要易於讀、易於理解,這樣別人纔會欣賞,也能夠給你提出合理化的建議。相反,若是繁雜難解的程序,其他人總是會避而遠之的。
5. 抽象原則
API的入參、出參所述的對象、屬性,一定是按業務特性進行抽象後的實體。誤將底層數據模型概念如實的反應到API上。抽象API、抽象對象實體更宏觀,具有更好的適用性、兼容性、擴展性。
6. 兼容擴展原則
對擴展開放,對修改關閉。保證API的向後兼容。
擴展參數應當是便利的,保證後續類似的需求,可以在已有的API上通過兼容擴展的方式實現。
7. 最小驚訝原則
代碼應該儘可能減少讓讀者驚喜。業務API只需根據需求來設計即可,不需要刻意去設計一下複雜無用、華而不實的API,以免弄巧成拙。
8. 低耦合原則
API應該減少對其他業務代碼的依賴關係。低耦合往往是完美結構系統和優秀設計的標誌。
耦合的種類:
- 代碼實現業務逆向調用。
- 條件邏輯依賴耦合。例如:此API在處理國稅網超訂單類型時,需要額外發送結算支付憑證上傳的事件MQ出來。
- 耦合API無關的業務行爲。例如:採購計劃鏈路日誌API被調用時,若是項目採購委託單的情況,需要額外調用公告的API拉取鏈路信息,新建成爲一條此委託單的一條鏈路日誌。
9. 正交原則
正交性是指改變某個特性而不會影響到其他的特性。
API之間的功能應該成正交性,無功能重合。API之間應該是互相補充的關係。
10. 易測試原則
對於API調用者而言,API應該是可被測試且易於被測試的。測試API不需要依賴額外的環境、容器、配置、公共服務等。
對可測試友好的API也是可被有效集成測試的前提。
11. 統一原則
API要具備統一的命名、統一的入/出參規範、統一的異常規範、統一的錯誤碼規範、統一的版本規範等。
統一規範的API優點:
- 易於被框架集成、處理
- 有助於API調用方、API提供方開發經驗複用
- 避免犯錯,避免誤用
來源:
blog.csdn.net/weixin_43318367/article/details/108746057