探索 .NET团队对API的设计流程
原文作者：steve gordon 原文鏈接: https://www.stevejgordon.co.uk/how-are-dotnet-apis-designed
在這篇文章中，我想介紹一些我覺得非常有趣的東西，.NET 團隊是如何設(shè)計API的？我們先來看下.NET團隊面臨的有哪些挑戰(zhàn)，您正在設(shè)計一套API庫，每天有數(shù)百萬的開發(fā)人員在使用這些庫，它們在世界各地運行在重要的應用程序上面，您要對其進行改進并添加新功能或增強功能，而且不能破壞數(shù)百萬個現(xiàn)有應用程序，這確實讓人頭大。
我喜歡編寫C＃代碼，自己也寫過很多API庫，其中很多都是內(nèi)部使用的庫，而使用這個庫的不到30人，即使這樣，我仍然寫了bug，那我得修啊，但我沒有意識到所有的環(huán)境下這個庫都是否可以使用， 以過去我的經(jīng)驗，我覺得設(shè)計公共API很困難。
在本文的其余部分中，我將按照我的理解來解釋.NET API設(shè)計過程，這些是我根據(jù)對這一過程進行了幾年的觀察而得出的自己的解釋，團隊所做的大部分工作都是公開發(fā)布的，因此可以從他們?nèi)绾谓M織.NET Core（和.NET 5）的API設(shè)計中學到很多東西。
為了使解釋更具體，我將遵循最近的新庫的設(shè)計，該庫將作為.NET 5的.NET BCL（基類庫）的一部分包括在內(nèi)，比如，System.Net.Http.Json?這個庫優(yōu)化了 HttpClient 處理Json，我今天不講這個庫如何使用，我們將專注于它是如何產(chǎn)生的。
1.設(shè)計階段 - Design
最開始，Immo Landwerth 發(fā)現(xiàn)在HttpClient中處理Json很麻煩，于是他在github提了一個json擴展的建議，里面包含了遇到了哪些問題，然后如何改進。
用簡單明了的術(shù)語，描述了這個設(shè)計如何變得更好，以及用戶（開發(fā)人員）對該功能的使用體驗，包括示例代碼，表達了開發(fā)人員會在什么情況下使用這個API。
在明確方案的情況下，接著繼續(xù)介紹新的API的要求,它必須實現(xiàn)什么目標，在什么時間范圍內(nèi)？然后是設(shè)計本身，該設(shè)計包括建議的公共API，但是沒有任何實現(xiàn)細節(jié), 這包括設(shè)計引入的所有公共方法和類型。
2.NET設(shè)計審查階段 - Review
.NET流程的下一個階段是進行API設(shè)計審查, 這在Github上面進行，團隊創(chuàng)建了一個 Issue，https://github.com/dotnet/runtime/issues/32937, 大家都有權(quán)限看到，這是公開的，因此社區(qū)可以征詢反饋和建議，我真的很喜歡這些.NET開放的氛圍！
API開始審查，在此會議上，.NET團隊的核心專家匯聚一堂，評估方案并確保公共API適合目標框架，這是至關(guān)重要的一步，為了兼容性，設(shè)計中的錯誤或疏忽可能會持續(xù)很長時間，這意味著API決策需要徹底，團隊也希望該API易于使用。
在API審核期間，會有人代表提案，并說明擬議設(shè)計的目標和原因，然后，團隊將對其進行討論，并確定提案是否需要進一步的工作，然后再批準，在被認為可以接受之前，可以在多次設(shè)計評審中提出一個API。
我真正欣賞團隊的一點是，他們在YouTube上現(xiàn)場直播了這次會議，任何人都可以觀看，盡管有時在會議期間聊天中留下的評論和反饋可能被認為是討論的一部分，但這主要是一種僅查看的方法，在YouTube上，.NET Foundation 頻道下的所有播放記錄都可以去瀏覽。
您可以在YouTube上查看HttpClient JSON擴展方法的設(shè)計的討論，https://www.youtube.com/watch?v=_AHbjIS8_0I
當我感興趣的API有討論的時候，我就會經(jīng)常上去看這些，我發(fā)現(xiàn)聽到討論并觀看.NET團隊對設(shè)計框架的想法非常有趣，在此過程中必須考慮許多細微的差異，這里面包含了大量的.NET 方面的知識，通常會提出一些細微的實現(xiàn)細節(jié)行為，例如現(xiàn)有API的歷史方面及其行為，可能觀看這樣一次會議，要花一兩個小時， 但我還是建議您有空可以參加其中的一些會議，來真正欣賞.NET框架的設(shè)計。
在審查期間，通常會使用GitHub Issue的標準做法, .NET的程序經(jīng)理 Immo Landwerth 通常主持會議并在討論過程中做筆記, 任何關(guān)注,反饋和更改都將記錄為設(shè)計審查的輸出。
3. 提交階段 - PR
一旦獲得批準，開發(fā)人員開始寫寫寫，來實現(xiàn)這個API，就像這個示例一樣，可能某些工作已經(jīng)試驗完成，然后還將需要把一些更改的內(nèi)容，記錄到設(shè)計評審的反饋中。
該功能的大部分工作由David Cantu完成，可以在GitHub上的拉取請求（PR）這里看到，https://github.com/dotnet/runtime/pull/33459 ， 同樣的它在Github，公開透明，任何人都可以訂閱通知，甚至發(fā)表評論。
我建議開發(fā)人員應該很熟悉這個階段，開發(fā)人員在git分支上完成了一些工作，一旦該工作完成并準備好考慮合并，就可以創(chuàng)建一個PR，一般可以直接合并到項目，但是出于質(zhì)量考慮，其他開發(fā)人員通常會進行一個或多個代碼審查，在Microsoft .NET世界中，這必須要考慮全面，因為不一致和性能問題可能是以后要解決的問題。
在這個例子中（Json擴展庫），我們可以看到很多評論，包擴多個有經(jīng)驗的專家，您將看到有關(guān)代碼復雜性的詳細反饋，這是我從提出和討論的小項目中學到很多東西的地方，隨著時間的推移，您可以觀看PR，甚至可以查看較新的提交，這些提交可以解決反饋并解決任何問題。
4.合并發(fā)布 - Release
一旦所有的審閱者批準了這個PR,然后這些代碼被合并到master分支中，因為.NET 運行時是一個非常復雜的庫，里面有高級的構(gòu)建過程，來處理這些新合并的代碼。
最終，新代碼將出現(xiàn)在相關(guān)庫的夜間版本中(nightly)，也可能被推送到MyGet或NuGet feed中以供預覽使用和測試，對于本篇的示例，生成了一個新程序包，并在NuGet上作為預發(fā)布預覽發(fā)布了該程序包
總結(jié)
這個過程非常有趣，我們了解到了.NET 團隊，最初由一個想法，再經(jīng)過設(shè)計，審查，討論，最終上線，這些都在Github進行，都是公開的，在這個過程中，我們可以學習非常全面的.NET的知識，因為微軟的專家處理這些事情，考慮的非常全面和細致。
最后
歡迎掃碼關(guān)注我們的公眾號 【全球技術(shù)精選】，專注國外優(yōu)秀博客的翻譯和開源項目分享，也可以添加QQ群 897216102
創(chuàng)作挑戰(zhàn)賽新人創(chuàng)作獎勵來咯，堅持創(chuàng)作打卡瓜分現(xiàn)金大獎總結(jié)
以上是生活随笔為你收集整理的探索 .NET团队对API的设计流程的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 如何在 ASP.NET Core 中写出
- 下一篇： ocelot 中间件的变化