如何保障API設計的穩定性

如何保障API設計的穩定性，針對這個問題，這篇文章詳細介紹了相對應的分析和解答，希望可以幫助更多想解決這個問題的小伙伴找到更簡單易行的方法。

計算機行業有句名言 —— 計算機科學領域的任何問題，都可以通過增加一個間接的中間層來解決。

當前的計算機領域，無論廣度還是深度，已經沒有一個人能完全掌握了。但是，通過各種中間層的組合使用，我們不需要了解其內部細節，也可以像搭積木一樣，開發出各種有趣的服務和應用。
而各個中間層之所以能組合工作，正是因為大家都通過定義好的 API 交互和通信。每個模塊在對外提供經過抽象 API 的同時，也需要使用其他模塊的 API 作為自身運行的基礎。

今天我們來聊聊在設計 API 過程保障穩定性的一些實踐。

無處不在的 API

API(Application Programming Interface) 又稱為應用編程接口。

而接口，本質可以理解為契約，一種約定。
計算機接口的概念起源于硬件。早期各家研發的各種元器件都不通用也沒有標準，相互使用非常困難，于是大家約定了功能和規格，就產生了接口，后來蔓延到軟件中。

接口蔓延到軟件之后，又分為 ABI(Application Binary Interface) 和 API(Application Programming Interface) 。
前者主要約定了二進制的運行和訪問的規則，后者則 專注于邏輯模塊的交互。本文以下內容僅討論開發者經常接觸的 API。

很多人對 API 的印象只是包含一些函數的 Class 或 頭文件。但 API 在我們生活中無處不在，只是我們有時并沒有注意到。

比如，當我們在撥打電話時，手機和基站通信的整個系統是非常復雜的。

好在我們不需要了解內部的細節，僅需要把 11 位的電話號碼傳給“電話系統”的接口就可以，而隱藏的國家區號（如+86）可以理解為接口的默認參數。
這個高度抽象的 API 背后，隱藏了非常多的細節。借助上面的中間層理論，我們可以系統性地討論設計一個 API 所需要考慮哪些內容。

模塊對上層暴露的 API 如何被使用？

API 從使用的耦合方式上，可以分為兩類：一種是通過協議調用，如調用 HTTP 接口；另一種是語言直接通過聲明調用。
如設計 HTTP Restful API 時，并不需要關心使用者的操作系統、使用的編程語言、內存線程管理等，因此會比后者簡單一些。

API 從使用者的規模和可控范圍上，可以分為 LSUD(Larget Set of Unkown Developers) 和 SSKD(Small Set of Kown Developers) 兩種。
前者一般都是公網開放的云服務，任何開發者都可以使用，無法提前預知以何種姿勢被使用，版本也不可控制。融云提供的通信云就是這種 API。
后者用戶群有限，一般都在同一家公司或團隊內。比如前段時間比較火的組件化，即對內提供的模塊化 API，使用范圍和方式均可控，在更新時一般不用太糾結向后兼容。

API 的第一受眾是人，然后才是機器，所以“可理解性”在設計時需要優先考慮。
而良好的 API 文檔、簡單扼要的 Demo、關鍵的 log，可以提升 API 使用者的體驗。

API 所屬模塊對下層有什么依賴？

API 所屬模塊都運行在一定的地址空間中。而其中的環境變量、加載庫、內存和線程模型、系統和語言特性都需要考慮。

API 所屬模塊的內部實現對其他層有什么影響？

一般而言，設計良好的 API 在使用時，并不需要理解其內部實現。但如果能了解其內部架構并輔助關鍵 log，有助于提升使用 API 的效率。
并且模塊的內部實現，有時也會影響到 API 設計的風格。
如一個強依賴 IO 的接口，可能需要使用異步的方式。大量異步的方式，就衍生出了 RxJava 等框架。

向后兼容

因為 API 如此重要，涉及的范圍又如此廣泛，廣大開發者對 API 的向后兼容可以說要求非常高。
畢竟誰也不想在開發過程中，頻繁的更新接口和代碼，想想《 swift 從入門到精通到再次入門到再再次入門》的慘案就心有余悸。

我們不僅問，為什么很多公司或者項目都無法向后兼容，僅僅是投入不夠或不夠重視，還是說 100% 的向后兼容實際就是不可能的？

假設設計是理想和經過論證的，正如一個完美的圓圈。
設計是要落實到編碼中的，而編碼的過程中總是不可避免的引入一些 bug，而帶著 bug 的某個版本實現，其實正如一個 Amoeba 變形蟲，形態是不固定的。而隨著版本不斷演進，不可避免會產生一定的差異。

第一個版本實現：

第二個版本實現：

所以說 100% 向后兼容本身就是不可能的。

因此，大家平時在談論 API 穩定性時，其實默認是可以包含一定程度變更的。

但由于 API 涉及的范圍太廣泛，保障向后兼容都需要極大代價。
比如 Linux 就希望快速迭代，完全不保證 API 的穩定性。針對這個問題，Linux 還特意寫了 stable-api-nonsense 文檔。
有興趣的可以點擊閱讀：stable-api-nonsense.rst

漸進式改進

所以說，保障 API 的穩定性會面臨很多挑戰，比如：
* 業務形態還不穩定，還在高速發展
* 業務和 API 歷史包袱較重
* 多個平臺和語言的特性不一致
* 用戶群和使用方式不明確

我們回顧一下正常的開發流程，看看是否能通過一些指標和工具，改善 API 的穩定性，主要涉及：需求、設計、編碼、Review、測試、發布、反饋等步驟。

※需求

普通的產品開發，在啟動的時候，用戶需求都比較明確，但對于 LSUD 的云服務而言，無法提前預知用戶群都有哪些，以及用戶在他的產品中如何使用 API。
這容易造成，沒有明確的用戶需求，API 就不好進行設計和迭代，沒有設計就沒有用戶，需求更無從談起。這是一個雞生蛋、蛋生雞的問題。

建議可以在 API 發布之前，內部先針對典型的使用場景，設計幾個完整的 Demo，驗證 API 的設計和使用是否合理。
需要注意的是，Demo 需要有完整應用場景，達到上架地步，如果能內部使用， Eating your own dog food 最好，過于簡單的 Demo 無法提前暴露 API 的使用問題。

Demo 的開發人員最好與 API 的設計者有所區分，避免思維固化，更多內容大家可以參照 Rust 語言開發在自舉過程中的一些實踐。

※設計

在設計 API 的時候，有很多需要注意的點和普通開發不太一樣。

普通開發，快速實現功能始終被放在第一位。比如大家會用一些敏捷開發的方式，優先實現功能再快速迭代等。
但 API 設計時，接口無法頻繁變更，所以首先需要考慮的是“少”，少即是多。

l 每個 API 做的事情要少

一個接口只做一件事，把這個事情做好就足夠了。
需要避免為了討好某個場景，在一個 API 上進行復雜的組合邏輯，提供一個類似語法糖的接口。否則，場景的業務自身在演進時，很難保證 API 的行為不變。
如果需要支持多種業務，可以考慮將 API 分層，比如融云客戶端的 API 會分為下面幾層。

舉個例子，融云考慮通用性，基于訂閱分發的模型，抽象了 RTCLib，客戶端能處理媒體的任意流，非常的靈活，但是對于用戶而言開發代價可能高些，要思考和做的工作比較多。
考慮到大量的用戶，其實需要的是音視頻通話的業務，基于 RTCLib，融云分裝了不帶 UI 的 CallLib 以及集成了 UI 的 CallKit。
如果一個用戶，需求和微信的音視頻通話類似，可以集成帶 UI 界面的 CallKit，開發效率會非常高；
如果用戶對通話音視頻通話 UI 的交互有大量需求，可以基于 CallLib 進行開發，對 UI 可以進行各種定制。

l 暴露的信息要少

成熟的 API 設計者都會盡可能的隱藏內部實現細節。
比如字段不應該直接暴露而是通過 Getter/Setter 提供，不需要的類、方法、字段都應該隱藏，都已經成為各個語言的基礎要求，在此就不細述了。
但容易被忽略的一點需要提醒大家，應盡量隱藏技術棧的信息。
比如：API http://api.example.com/cgi-bin/get_user.php?user=100，就明顯混入了很多無用的信息，并且以后技術切換升級想維持 API 穩定非常麻煩。

l 行為擴散要少

在語言直接調用的 API 中，需要避免基礎接口通過繼承導致行為擴散。
在普通的編碼過程中，抽象類和繼承都是面向對象的強大武器。但是對于 API，更建議通過組合使用。
比如一個管理生命周期的類，如果被繼承，子類有些行為就有可能被修改而導致出錯。這時候建議使用 Interface + 工廠的方法提供實例。
由于 Java 8 之前 interface 沒有 default 實現，為了避免增加功能需要頻繁修改接口，可以使用 final class。
Objetive-C 則可以使用 __attribute__((objc_subclassing_restricted)) 和 __attribute__((objc_requires_super) 控制子類繼承行為。

l 畫風切換要少

API 命名要做到多個平臺的業務命名統一，與每個平臺的風格統一。
這點 HTTP 的接口要簡單一些，只需要選定一種風格即可，Restful 或者 GraphQL 或者自己定義。
語言調用的 API 命名，建議首先遵循平臺的風格，然后再是參考語言標準，最后才考慮團隊的風格。
比如：iOS 平臺的 API 開發，需要首先參照 iOS 的命名風格，did 和 will 之類的時態就非常有特色。
命名上細節較多，詞匯、時態、單復數、介詞、?小寫、同步異步風格等都需要考量，需要長時間的積累。

l 理解成本要少

一般 API 每個接口都會有相應的注釋說明，但是值得注意的是，大部分開發者并不看注釋。
大部分開發者對接口的了解，都僅源于 IDE 的補全和提醒。一個接口看著像就直接用，不行再換一個試試，這其實是一種經驗式編程的方式。
也就意味著接口命名需要提高可理解性。有一個辦法可以驗證，將接口的所有注釋抹掉，使用者能否非常直接的看懂每個接口的含義。如果很困難，則需要改進。

API 設計還有一處和普通開發不太一致。普通開發設計好架構即可，每個模塊的開發可能是同一個人，接口并不需要在設計時確定下來。
但是 API 的設計階段，需要進行 Review 并直接確定接口的設計，以保證多端在開發時遵循完全一直的規則。

※編碼

在 API 的編碼過程中，有以下幾點需要注意。

在 API 中，預定義好版本號。
這個主要是針對 HTTP API，如：http://api.example.com/v1/users/12345?fields=name,age。 如果目前僅有一個版本，也可以暫時不加，第二版時再區分。

注意 API 版本檢查。
當分層提供多種 API 時，每層 API 需要在啟動時，先校驗一下版本號，避免不匹配的情況。
比如在以下 Java 代碼中，大家可能覺得判斷版本號相等的代碼非常奇怪，應該永遠是 true 才對。

但是抽象類和實現類出現在不同的分層模塊中，并且實現類先編譯，抽象類版本更新后再編譯，就會出現不一致的情況。有很多語言或平臺能提供類似的方式來確定版本。

提供規范性的 log 輸出。
普通開發的log，主要用于自己定位問題。但是 API 在編碼時，最好針對性的添加一些 log，有利于 API 的使用者理解并簡單排查問題。
但出于性能考慮，需要定義好 log 的級別并可以調整。

注意廢棄與遷移。
當一個以前設計的 API 不再符合要求或者有重大問題時，我們可以對外標記成已廢棄，并在注釋中建議使用者遷移到另一個接口。
如果是類似的被廢棄接口，內部編碼時最好能使用新的接口來實現，以降低向后兼容的維護成本。
HTTP 的 API，需要預定義好遷移的錯誤碼，比如在 HTTP 規范中，可以使用 410 Gone 說明已經不再支持某個接口。

※Review

API 的 Review 基于普通開發的 Code Review。
如果基礎的 Code Review 都沒有做好，肯定無法保障 API 的質量和穩定性。

可以通過一些工具，為 API 的 Review 提供一些參考報告。
比如可以使用 SonarLint 分析代碼復雜度，如果接口層的代碼復雜度較高，會是一個危險的信號。
還可以借助 Java 反射、Clang 語法分析，獲取當前的 API 接口列表，生成接口變更報告，也有利于減少無用接口的暴露。
另外，自動化工具生成的接口文檔也是 Review 重要的一環。

※測試

在測試環節，我們可以通過 unit test 來關注 API 的穩定性。
與敏捷開發經常修改 test case 不同，API 的 test case 基本代表了接口的穩定性。所以在修改舊 case 時需要特別明確，是 case 自身的 bug 還是接口行為發生了變更。

※發布

我們可以通過區分 dev 和 stable 版本，為不同階段的開發者提供更好的體驗。

dev 版本包含最新的功能，但是 API 接口有變更風險。stable 版本 API 穩定，但功能不一定是最新的。
如果開發者還在開發過程中，可以選用最新的 dev 版本，基于最新 API 開發。
如果應用已經上線，可以選擇升級直接到最新的 stable 版本。

關于如何保障API設計的穩定性問題的解答就分享到這里了，希望以上內容可以對大家有一定的幫助，如果你還有很多疑惑沒有解開，可以關注億速云行業資訊頻道了解更多相關知識。