> Photo by Startup Stock Photos from Pexels
API是應用程序編程接口。 這是一個程序向其他程序提供服務的一種結構化方式。
簡單來說，就像在餐廳點菜。 你不能去廚房做飯。 您會看到一個菜單，並且您知道廚房正在做飯。 您使用服務員下訂單。
服務員是API，它將您的請求帶到準備它的廚房並帶回給您。
類似地，某人（例如Facebook）為API提供了帶有各種參數的有限命令菜單。 您的程序使用此API下訂單，Facebook會開始執行該訂單。
引用丹尼爾·傑克遜的話：
軟件建立在抽象之上。 選擇合適的程序，編程將自然而然地從設計中產生。 模塊將具有小而簡單的界面； 而無需進行大量重組，新功能就很可能適用。 選擇錯誤的程序，編程將帶來一系列令人討厭的驚喜。
優質API的特點：
一個好的API是
· 簡單易學
· 導致可讀代碼
· 難以濫用
· 易於擴展和
· 完備
簡單易學
為了使API易於學習，它必須具有一致的命名約定和模式，對概念的仔細管理以及可預測性。 對於相似的概念，它使用相同的名稱，對於不同的概念，它使用不同的名稱。 用戶必須能夠重新應用他們在API的另一部分中學到的知識。
組成它的不僅是名稱和方法，還包括其預期的語義，這些語義應該簡單明瞭。 有些API很難學習，因為它們需要用戶編寫大量的樣板代碼才能入門。 易於學習的API使得僅用幾行簡單的代碼即可編寫" hello world"示例，並逐步對其進行擴展以獲得更復雜的程序。
導致可讀代碼
有時即使一個庫易於學習和記憶，它仍然可能導致完全不透明的代碼。 API必須是可讀的，因為應用程序代碼僅編寫一次，但是在應用程序的生命週期中由不同的開發人員反覆讀取。
可讀代碼更易於閱讀和維護，即使存在錯誤，由於代碼的可讀性，它也更易於調試。 另外，可讀代碼始終處於正確的抽象級別上-既不隱藏重要內容，也不強迫程序員指定不相關的信息。
難以濫用
精心設計的API使編寫正確的代碼比編寫錯誤的代碼更容易，並鼓勵良好的編程習慣。 它不會不必要地強迫用戶嚴格按順序調用方法或意識到隱性副作用。 通過消除冗餘，我們可以使API難以濫用。
易於擴展
API的設計應考慮到增長。 在初始階段，應該仔細考慮諸如新類，現有類的新方法，方法的新參數等內容。
完備
幾乎不可能為任何內容提供完整的API，但是至少用戶應該可以擴展或定製現有的API。 因此，API將是完整的，並允許用戶執行他們想要的一切。
通過向現有API逐步添加功能，完整性會隨著時間的流逝而出現。 但是，即使在那種情況下，通常也有助於明確未來的發展方向，因此每次添加都是朝著正確方向邁出的一步。
設計過程：
這需要幾年的時間，並且需要很多人來構建良好的API。 流程的每個步驟都提供了改進API或破壞API的機會。
羅馬不是一天建成的。
瞭解要求
在著手設計API之前，請先對這些要求有所瞭解。 在大多數情況下，您將需要進行某種需求分析。 一個好的出發點是向儘可能多的人（尤其是您的老闆，同事和潛在用戶）詢問他們希望看到哪些功能。
在編寫任何其他代碼之前先編寫用例
該實現應適應用戶，而不是相反。 為此，在編寫實現代碼甚至設計API之前，首先要根據需求列表編寫一些典型的應用程序代碼片段。 在此階段，不必擔心實施API會遇到的困難。 在編寫代碼段時，API逐漸成形。
這些片段應反映Perl的座右銘，
"讓輕鬆的事情變得容易，而讓困難的事情變得可能"。
在實現之前定義API
在定義API之前，應在實現API之前先指定API及其語義。 對於具有數千個用戶的庫，如果API很簡單。 有時實現起來可能會很棘手，但這沒關係。
API及其語義是庫提供的主要產品。 經驗一次又一次地表明API比其實現更持久。
讓您的同事查看您的API
尋找，詢問甚至乞求反饋。 向您的同行展示您的API，並收集您獲得的所有反饋。 嘗試忘記實施請求的更改將需要進行多少工作。 當收到負面反饋時，請相信所有反饋都是有用的原則。 任何意見都是一條新的信息，您可以將其重鑄為事實並添加到您的事實心智表中。
您擁有的事實越多，設計好的API的機會就越大。
準備擴展
設計API之後，請務必編寫一些使用該API的示例。 使用API的人提供的反饋和示例將非常有用。
API可以通過兩種方式擴展：
· 由維護者（添加/棄用）和
· 由將自定義API行為的用戶決定。
規劃可擴展性需要仔細考慮實際情況並考慮可能的解決方案。 如果您對API或功能有疑問，請將其排除在外，稍後再重新考慮。 它通常有助於等待用戶的反饋。 實際上，不可能添加用戶建議的所有功能。 一個好的經驗法則是等到大量用戶獨立地要求功能後再實施它。
設計準則：
遵循準則，在設計API時無疑會改進它。 希望這些指南能幫助您正確使用API。 您可以在流程的各個階段再次參考這些內容。
對於許多準則，可能會有同樣真實的反準則（牛頓第三定律，大聲笑）。 例如，
· "避免使API過於聰明"和"避免使API過於愚蠢"
· "注意邊緣情況"和"關注一般情況"
API設計如此令人鼓舞的原因是，需要考慮產生相互矛盾的需求。 但最後，這些都無法替代您的大腦。
命名
· 選擇不言自明的名稱和簽名。 方法的參數含義應該清楚。 布爾參數通常會導致代碼無法讀取，因此請注意這些內容。 並爭取一致性。 固定參數順序時，一致性特別重要。 避免使用單字母名稱。
· 為相關事物選擇不同的名稱。 如果需要區分兩個或更多個相似的概念，請選擇與它們所表示的概念清晰對應的名稱。 任何人都可以輕鬆地將名稱與正確的概念相關聯，而無需在文檔中查找它們。
· API應該顯示出良好的對稱性。 形式的相似性使用戶能夠識別內容和功能的相似性。 另一方面，功能的不對稱性應由形式的不對稱性反映出來。 如果您習慣給setter方法加上" set"（例如setValue（））作為前綴，那麼對於那些不是setter的方法，請避免使用該前綴。
· 避免縮寫。 如果有縮寫，則意味著用戶必須記住哪些詞是縮寫。 通常避免這種情況。 可以允許使用非常常用的形式，例如" min"，" max"，" rect"，" prev"等，但是必須一致地應用此約定。 這不適用於首字母縮寫詞。
· 優先使用特定名稱而不是通用名稱。 特定名稱使用戶更易於聯繫，因為可能有數百個需要不同名稱的類。
語義學
· 選擇良好的默認設置，這樣用戶就不必只是為了入門而複製和粘貼或編寫樣板代碼。 選擇良好的默認值，我們不僅要消除樣板代碼，還可以使API簡單且可預測。
· 注意邊緣情況。 邊緣情況很重要，因為它們往往會在API中產生波動。 例如，如果您的基本字符串搜索算法的邊緣情況不正確，這可能會導致正則表達式引擎中的錯誤，從而導致使用正則表達式的應用程序中的錯誤。 首先處理一般情況，而不必擔心邊緣情況。 通常，您不需要任何額外的代碼來處理邊緣情況。 沒人需要計算0的階乘函數！ = 0，哈哈。 但是，請確保在單元測試中正確覆蓋了邊緣情況。
結論
設計API並不容易。 這需要大量的耐心和努力。 希望本文對您有所幫助。 當然，我可能已經錯過了一些東西，請隨時讓我知道。
祝好運並玩得開心點！
(本文翻譯自Deepak Surya的文章《API Design 101》，參考：https://medium.com/@
ideepaksuryas/api-design-101-4da3e1d1767)
