原文連結: https://www.stevejgordon.co.uk/how-are-dotnet-apis-designed

在這篇文章中，我想介紹一些我覺得非常有趣的東西，.NET 團隊是如何設計API的？ 我們先來看下.NET團隊面臨的有哪些挑戰，您正在設計一套API庫，每天有數百萬的開發人員在使用這些庫，它們在世界各地執行在重要的應用程式上面，您要對其進行改進並新增新功能或增強功能，而且不能破壞數百萬個現有應用程式，這確實讓人頭大。

我喜歡編寫C＃程式碼，自己也寫過很多API庫，其中很多都是內部使用的庫，而使用這個庫的不到30人，即使這樣，我仍然寫了bug，那我得修啊，但我沒有意識到所有的環境下這個庫都是否可以使用， 以過去我的經驗，我覺得設計公共API很困難。

在本文的其餘部分中，我將按照我的理解來解釋.NET API設計過程，這些是我根據對這一過程進行了幾年的觀察而得出的自己的解釋，團隊所做的大部分工作都是公開發布的，因此可以從他們如何組織.NET Core（和.NET 5）的API設計中學到很多東西。

為了使解釋更具體，我將遵循最近的新庫的設計，該庫將作為.NET 5的.NET BCL（基類庫）的一部分包括在內，比如， System.Net.Http.Json 這個庫優化了 HttpClient 處理Json，我今天不講這個庫如何使用，我們將專注於它是如何產生的。

最開始，Immo Landwerth 發現在HttpClient中處理Json很麻煩，於是他在github提了一個json擴充套件的建議，裡面包含了遇到了哪些問題，然後如何改進。

用簡單明瞭的術語，描述了這個設計如何變得更好，以及使用者（開發人員）對該功能的使用體驗，包括示例程式碼，表達了開發人員會在什麼情況下使用這個API。

在明確方案的情況下，接著繼續介紹新的API的要求,它必須實現什麼目標，在什麼時間範圍內？然後是設計本身，該設計包括建議的公共API，但是沒有任何實現細節, 這包括設計引入的所有公共方法和型別。

.NET流程的下一個階段是進行API設計審查, 這在Github上面進行，團隊建立了一個 Issue， https://github.com/dotnet/runtime/issues/32937 , 大家都有許可權看到，這是公開的，因此社群可以徵詢反饋和建議，我真的很喜歡這些.NET開放的氛圍！

API開始審查，在此會議上，.NET團隊的核心專家匯聚一堂，評估方案並確保公共API適合目標框架，這是至關重要的一步，為了相容性，設計中的錯誤或疏忽可能會持續很長時間，這意味著API決策需要徹底，團隊也希望該API易於使用。

當我感興趣的API有討論的時候，我就會經常上去看這些，我發現聽到討論並觀看.NET團隊對設計框架的想法非常有趣，在此過程中必須考慮許多細微的差異，這裡麵包含了大量的.NET 方面的知識，通常會提出一些細微的實現細節行為，例如現有API的歷史方面及其行為，可能觀看這樣一次會議，要花一兩個小時， 但我還是建議您有空可以參加其中的一些會議，來真正欣賞.NET框架的設計。

一旦獲得批准，開發人員開始寫寫寫，來實現這個API，就像這個示例一樣，可能某些工作已經試驗完成，然後還將需要把一些更改的內容，記錄到設計評審的反饋中。

我建議開發人員應該很熟悉這個階段，開發人員在git分支上完成了一些工作，一旦該工作完成並準備好考慮合併，就可以建立一個PR，一般可以直接合併到專案，但是出於質量考慮，其他開發人員通常會進行一個或多個程式碼審查，在Microsoft .NET世界中，這必須要考慮全面，因為不一致和效能問題可能是以後要解決的問題。

在這個例子中（Json擴充套件庫），我們可以看到很多評論，包擴多個有經驗的專家，您將看到有關程式碼複雜性的詳細反饋，這是我從提出和討論的小專案中學到很多東西的地方，隨著時間的推移，您可以觀看PR，甚至可以檢視較新的提交，這些提交可以解決反饋並解決任何問題。

一旦所有的審閱者批准了這個PR,然後這些程式碼被合併到master分支中，因為.NET 執行時是一個非常複雜的庫，裡面有高階的構建過程，來處理這些新合併的程式碼。

最終，新程式碼將出現在相關庫的夜間版本中(nightly)，也可能被推送到MyGet或NuGet feed中以供預覽使用和測試，對於本篇的示例，生成了一個新程式包，並在NuGet上作為預釋出預覽釋出了該程式包

這個過程非常有趣，我們瞭解到了.NET 團隊，最初由一個想法，再經過設計，審查，討論，最終上線，這些都在Github進行，都是公開的，在這個過程中，我們可以學習非常全面的.NET的知識，因為微軟的專家處理這些事情，考慮的非常全面和細緻。