探索 .NET團隊對API的設計流程

原文做者：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