設計、編寫、維護一個穩定的API

1.首先建立一個基本的術語庫

描述整個API設計的需求出現緣由，并概述各設計過程的主要目標。

2.設計API時，取一個獨一無二的名字，且聞其名知其意（自描述的）

3.設計API的環境要求： 最好做到自己可以處理所需的運行環境

工程師多花點兒時間和精力列出組件所依賴的內容

API就是模塊化的代碼，模塊化程序可以由很多小的獨立代碼段組成。

這些小的代碼段是獨立存在，并且唯一標識，通過公開接口的方式供他人使用。

問題： API的庫一直動態變化發展的，API是有版本號的，一般都需要向下兼容，如版本5兼容版本4的內容。

A 細心開發各自組件和相應的API

B并且保證兼容性

軟件版本的非線性 1 ? ? ? ? ? ? ? 2 ? ? ? ? ? ? ? 3 1.1 ? ? ? ? ? ?1.2 1.1.1
需要質量控制部門， 規則一： 如果發布了一個新的版本，那么前一個版本提供的功能和約定，對于新版本應該繼續有效。 規則二：如果本組件的外部依賴有改變，那么就需要與其同步調整。 軟件版本有兩個版本號 標準版本號+實現版本號（通常是一個字符串） 1.1 ? ? ? ? ? ? ? ? Build20170204001 一個管控者，對系統進行檢查，保證所有已安裝的模塊能夠保持一致性 多溝通： 如，郵件，電話會議，API自身及相關文檔
經驗主義編程方式： 先用一個API做個實驗，如果不成功，再試一下別的。經驗第一，然后才是深入了解。

注意要點：

1.設計的?API?返回值最好不能為空（默認規則） 2.創建一些能夠復制和容易修改的示例代碼，對第一次試用API的程序員很有幫助。 3.API新版本：增加用戶信任，盡量避免破壞兼容性 將一些內容標識為不建議試用，然后明確以文檔的形式來告訴用戶如何將現有的系統遷移到新組件。 4. 設計的API，在今后的版本中，可能功能不夠用或者完全無用了 設計時，需要做好可以隨時改變的準備，而且不破壞其用戶的現有代碼 5.改進API是最重要的內容，可以通過言論自由，先廣納建議，再確定是否添加這項功能，即使第一個版本功能很少，只完成其中之一個的文檔和說明，其他內容很丑陋，但沒有關系，下一個版本慢慢改進即可。 6.衡量API質量 (1) 漂亮，這是一種優勢，但不是唯一標準，因為每個人對漂亮的標準不一樣（無法量化） (2) 易于使用、廣為接受且富有成效
(3) 應有詳細規則，以確保符合客觀標準
(4) 可理解性： 使用API的用戶必須能夠理解API
API設計者需理解其目標用戶普遍具有的知識，在此基礎上設計API。如果引入新知識，應是漸進式的，而且要有實例進行幫助使用API 。 (5) 一致性： 一是API版本間保持一致；二是一個API對外提供功能一致。 (6)?可見性：容易找到入口，易于使用 (7)?簡單的任務應該有簡單的方案：針對不同的API受眾應該放到不同API中，這樣可以提高程序的可見性 因為某些開發人員只關心某一方面的功能，而其他功能可能會影響使用人員學習 一般情況：一個API分成兩個或者多個組成部分，一部分用來針對調用功能的開發人員；一部分應該放在獨立的包中，或者有其特定的命名空間，用來方便他人擴展當前的模塊功能。 (8)保護投資：為用戶考慮一些，不要破壞現有的代碼，保護其用戶投入的資源 爭取永遠以一種兼容的（或者至少是可以預測的）方式來演進API契約。只要有可能出現不兼容的問題，一定要提前調整好對升級需求的期待。 或者很容易編譯出新的版本（不嚴謹，但Linux就是這樣做的） 發布第一個版本之前可以修改方法名稱或者API結構。一旦發布，盡量不修改

有些調用者： 反射調用內容，有時對新版本失效，原因（這些內容不是公開的API，不承諾兼容性）

API就像恒星，一旦被發現，就永遠待在那里
每個協議建立連接時，即使這個協議只是在本地系統上用于內部交互，第一件要做的事情就是一個握手協議，明確一些關鍵信息，如連接雙方的版本，以便他們選擇通用的語言進行交流，支持常見情況就可以。
升級時，隱藏相關操作
環境： 系統語言和環境對API是有影響的。

4不斷變化的目標?

API發布的版本，僅僅是整個生命周期的起點，判斷其是否優秀，需要看多年后，該API是否能依然存在，是否仍然保持的不錯。

4.1第一個版本遠非完美

第一個版本容易開發、容易發布。每個程序都會存在bug，而且通常情況下修復一個bug的同時可能會引入兩個新bug。 為未來做考慮，考慮未來會對API中的那些內容加以改進。兩種方式，其一是放棄老版本，重新開始做一套新系統；其二是修正用戶提出的問題，強化現有API，保證兼容性。
增量改進：理想情況下，可以做到修正bug，提高程序性能，并提供更漂亮的界面，這一切都不需要用戶付出額外的工作。 棄舊創新：可以避免不兼容，并且可以引入創新和更好的功能。問題，使用舊API的用戶只能繼續沿用舊API，除非重新編寫他們的代碼，升級到API新版本上。

4.2向后兼容

4.2.1 源代碼兼容（原先API接口名稱不變即可，而且功能可以增加）

如，API版本1.3兼容版本1.2 即，編寫的代碼可以同時在老版本和新版本上都編譯通過

4.2.2二進制兼容（.h 文件不變，應該就可以達到這種效果）

編譯后的老版本代碼在執行時，不需要重新編譯可以和API新版本進行正常連接執行，稱作二進制兼容。 好處：靈活 1.用戶可以極大的簡化程序的維護、打包和發布工作 2.靈活，用戶可以先用老版本API進行開發，最后移植到新版本API即可 要求，API開發人員至少需要了解一些源代碼編譯后生成的二進制格式

源代碼兼容和二進制兼容區別

Java中使用方法優于使用字段

4.2.3功能兼容---阿米巴變形蟲效應

各個模塊能夠按照設計時的目標正確運作 如果一個類庫在運行時，不管所引用的是老版本還是新版本的API，其產生的結果完全相同，就是功能兼容。 所以公開的功能或者說行為也都需要考慮兼容性
開發API的人員 1.需要對API要完成的功能有清楚的認識 2.具備良好的即使水平 3.評估用戶如何使用這個API（還要想一下這些用戶如何來誤用API）

4.3面向用例的重要性

站在用戶的角度來理解和設計API庫。 方法 1.找一些用戶，對其進行研究，假想一下用戶的用例 2.基于用例設計（有點兒像UML啊。。。） 設計前需要了解 1.為什么要寫這樣的API 2.API應該長什么樣子 3.如何才能完成目標 用戶只會對一種情況感到滿意： 可以很容易地使用API來完成其工作。
一個用例代表對API一種用戶的描述
最新規范，其實都是在程序員的腦袋里，根本沒辦法檢測好還是壞 用例---場景---文檔

4.4API設計評審

開始： 所有的API都由一位架構師來開發 --->接下來發現架構師成為了項目的瓶頸（壓力山大啊，需要考慮設計、維護API、告訴別人如何使用這個API） --->改由一個架構師指導一個團隊來設計API（剛剛的架構師在團隊中選擇一些技術最好的人，指導他們設計自己所需的API） API 就是開發人員與用戶之間的一種溝通方式 --->增加一個團隊來配合API的開發者對API的評審工作 此時，一旦有一個API需要改的，任何人都可以提交一個改變的請求。其他人則需要在代碼正式提交前，進行一次評審，檢測新調整的內容是否符合一個優秀API的基本要求。

優秀API規則

用例驅動的API設計：設計API時，要基于一些具體的場景和對API的認識進行抽象分析，最終給出設計。 API設計的一致性：API往往是由多為設計者來完成的，但整個團隊中必須能夠保持“最佳實踐”的一些基本原則。一個接口設計的再好，只要它違反整個團隊的一致性，就寧愿退而求其次。 簡單明了的API：而且常見的任務應該更容易處理。用例驅動的設計可以通過簡單實現場景來驗證。 少即是多：一個API對外提供的功能應該只包括用例中說明的功能。這樣可以避免出現需要的功能與實際提供的功能兩者之間出現的差異。 支持改進：以后也必須能夠維護這個類庫。如果出現新的需求，或者原作者離開，都不會出現放棄這個類庫的情況。
負責API評審的人：向團隊成員解釋為什么要這樣設計API；以及API設計的內容；設計的工作分配給不同的人

4.5一個API的生命周期

API 是溝通交流的工具，雙方是API用戶和API設計者 API設計： 收集需求 定義問題域 明確用例 再由指定人員來設計API
其他人只是使用這個API，給出建議，列出bug，提出改進意見 API 要有狀態，標識當前狀態，以便用戶了解相應版本是否穩定 如， Linux 1.2 ，1.4， 1.6 都是穩定版本； 1.1,1.3,1.5 都是不穩定版本?

API分類 1. Private 對于那種僅供內部使用，不公開給外部開發人員使用的模塊或者類庫 內容：API只包括 環境配置文件以及讀取文件的代碼 2. Friend 為系統內部其他模塊提供相應功能的API 內容：每個模塊提供一個Friend列表，明確告訴系統哪些模塊可以訪問它提供的API

總結

以上是生活随笔為你收集整理的软件框架-无绪开发的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。