原文作者：steve gordon
原文連結: 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，我今天不講這個庫如何使用，我們將專注於它是如何產生的。
1.設計階段 - Design
最開始，Immo Landwerth 發現在HttpClient中處理Json很麻煩，於是他在github提了一個json擴充套件的建議，裡面包含了遇到了哪些問題，然後如何改進。
用簡單明瞭的術語，描述了這個設計如何變得更好，以及使用者（開發人員）對該功能的使用體驗，包括示例程式碼，表達了開發人員會在什麼情況下使用這個API。
在明確方案的情況下，接著繼續介紹新的API的要求,它必須實現什麼目標，在什麼時間範圍內？然後是設計本身，該設計包括建議的公共API，但是沒有任何實現細節, 這包括設計引入的所有公共方法和型別。
2.NET設計審查階段 - Review
.NET流程的下一個階段是進行API設計審查, 這在Github上面進行，團隊建立了一個 Issue，https://github.com/dotnet/runtime/issues/32937, 大家都有許可權看到，這是公開的，因此社群可以徵詢反饋和建議，我真的很喜歡這些.NET開放的氛圍！
API開始審查，在此會議上，.NET團隊的核心專家匯聚一堂，評估方案並確保公共API適合目標框架，這是至關重要的一步，為了相容性，設計中的錯誤或疏忽可能會持續很長時間，這意味著API決策需要徹底，團隊也希望該API易於使用。
在API稽核期間，會有人代表提案，並說明擬議設計的目標和原因，然後，團隊將對其進行討論，並確定提案是否需要進一步的工作，然後再批准，在被認為可以接受之前，可以在多次設計評審中提出一個API。
我真正欣賞團隊的一點是，他們在YouTube上現場直播了這次會議，任何人都可以觀看，儘管有時在會議期間聊天中留下的評論和反饋可能被認為是討論的一部分，但這主要是一種僅檢視的方法，在YouTube上，.NET Foundation 頻道下的所有播放記錄都可以去瀏覽。
您可以在YouTube上檢視HttpClient JSON擴充套件方法的設計的討論，https://www.youtube.com/watch?v=_AHbjIS8_0I
當我感興趣的API有討論的時候，我就會經常上去看這些，我發現聽到討論並觀看.NET團隊對設計框架的想法非常有趣，在此過程中必須考慮許多細微的差異，這裡麵包含了大量的.NET 方面的知識，通常會提出一些細微的實現細節行為，例如現有API的歷史方面及其行為，可能觀看這樣一次會議，要花一兩個小時， 但我還是建議您有空可以參加其中的一些會議，來真正欣賞.NET框架的設計。
在審查期間，通常會使用GitHub Issue的標準做法, .NET的程式經理 Immo Landwerth 通常主持會議並在討論過程中做筆記, 任何關注,反饋和更改都將記錄為設計審查的輸出。
3. 提交階段 - PR
一旦獲得批准，開發人員開始寫寫寫，來實現這個API，就像這個示例一樣，可能某些工作已經試驗完成，然後還將需要把一些更改的內容，記錄到設計評審的反饋中。
該功能的大部分工作由David Cantu完成，可以在GitHub上的拉取請求（PR）這裡看到，https://github.com/dotnet/runtime/pull/33459 ， 同樣的它在Github，公開透明，任何人都可以訂閱通知，甚至發表評論。
我建議開發人員應該很熟悉這個階段，開發人員在git分支上完成了一些工作，一旦該工作完成並準備好考慮合併，就可以建立一個PR，一般可以直接合併到專案，但是出於質量考慮，其他開發人員通常會進行一個或多個程式碼審查，在Microsoft .NET世界中，這必須要考慮全面，因為不一致和效能問題可能是以後要解決的問題。
在這個例子中（Json擴充套件庫），我們可以看到很多評論，包擴多個有經驗的專家，您將看到有關程式碼複雜性的詳細反饋，這是我從提出和討論的小專案中學到很多東西的地方，隨著時間的推移，您可以觀看PR，甚至可以檢視較新的提交，這些提交可以解決反饋並解決任何問題。
4.合併釋出 - Release
一旦所有的審閱者批准了這個PR,然後這些程式碼被合併到master分支中，因為.NET 執行時是一個非常複雜的庫，裡面有高階的構建過程，來處理這些新合併的程式碼。
最終，新程式碼將出現在相關庫的夜間版本中(nightly)，也可能被推送到MyGet或NuGet feed中以供預覽使用和測試，對於本篇的示例，生成了一個新程式包，並在NuGet上作為預釋出預覽釋出了該程式包
總結
這個過程非常有趣，我們瞭解到了.NET 團隊，最初由一個想法，再經過設計，審查，討論，最終上線，這些都在Github進行，都是公開的，在這個過程中，我們可以學習非常全面的.NET的知識，因為微軟的專家處理這些事情，考慮的非常全面和細緻。
最後
歡迎掃碼關注我們的公眾號 【全球技術精選】，專注國外優秀部落格的翻譯和開源專案分享，也可以新增QQ群 897216102
