原文作者：steve gordon 原文鏈接: https://www.stevejgordon.co.uk/how-are-dotnet-apis-designed

在這篇文章中，我想介紹一些我覺得非常有趣的東西，.NET 團(tuán)隊(duì)是如何設(shè)計(jì)API的？我們先來看下.NET團(tuán)隊(duì)面臨的有哪些挑戰(zhàn)，您正在設(shè)計(jì)一套API庫，每天有數(shù)百萬的開發(fā)人員在使用這些庫，它們在世界各地運(yùn)行在重要的應(yīng)用程序上面，您要對其進(jìn)行改進(jìn)并添加新功能或增強(qiáng)功能，而且不能破壞數(shù)百萬個(gè)現(xiàn)有應(yīng)用程序，這確實(shí)讓人頭大。

我喜歡編寫C＃代碼，自己也寫過很多API庫，其中很多都是內(nèi)部使用的庫，而使用這個(gè)庫的不到30人，即使這樣，我仍然寫了bug，那我得修啊，但我沒有意識到所有的環(huán)境下這個(gè)庫都是否可以使用， 以過去我的經(jīng)驗(yàn)，我覺得設(shè)計(jì)公共API很困難。

在本文的其余部分中，我將按照我的理解來解釋.NET API設(shè)計(jì)過程，這些是我根據(jù)對這一過程進(jìn)行了幾年的觀察而得出的自己的解釋，團(tuán)隊(duì)所做的大部分工作都是公開發(fā)布的，因此可以從他們?nèi)绾谓M織.NET Core（和.NET 5）的API設(shè)計(jì)中學(xué)到很多東西。

為了使解釋更具體，我將遵循最近的新庫的設(shè)計(jì)，該庫將作為.NET 5的.NET BCL（基類庫）的一部分包括在內(nèi)，比如，System.Net.Http.Json?這個(gè)庫優(yōu)化了 HttpClient 處理Json，我今天不講這個(gè)庫如何使用，我們將專注于它是如何產(chǎn)生的。

1.設(shè)計(jì)階段 - Design

最開始，Immo Landwerth 發(fā)現(xiàn)在HttpClient中處理Json很麻煩，于是他在github提了一個(gè)json擴(kuò)展的建議，里面包含了遇到了哪些問題，然后如何改進(jìn)。

用簡單明了的術(shù)語，描述了這個(gè)設(shè)計(jì)如何變得更好，以及用戶（開發(fā)人員）對該功能的使用體驗(yàn)，包括示例代碼，表達(dá)了開發(fā)人員會在什么情況下使用這個(gè)API。

在明確方案的情況下，接著繼續(xù)介紹新的API的要求,它必須實(shí)現(xiàn)什么目標(biāo)，在什么時(shí)間范圍內(nèi)？然后是設(shè)計(jì)本身，該設(shè)計(jì)包括建議的公共API，但是沒有任何實(shí)現(xiàn)細(xì)節(jié), 這包括設(shè)計(jì)引入的所有公共方法和類型。

2.NET設(shè)計(jì)審查階段 - Review

.NET流程的下一個(gè)階段是進(jìn)行API設(shè)計(jì)審查, 這在Github上面進(jìn)行，團(tuán)隊(duì)創(chuàng)建了一個(gè) Issue，https://github.com/dotnet/runtime/issues/32937, 大家都有權(quán)限看到，這是公開的，因此社區(qū)可以征詢反饋和建議，我真的很喜歡這些.NET開放的氛圍！

API開始審查，在此會議上，.NET團(tuán)隊(duì)的核心專家匯聚一堂，評估方案并確保公共API適合目標(biāo)框架，這是至關(guān)重要的一步，為了兼容性，設(shè)計(jì)中的錯(cuò)誤或疏忽可能會持續(xù)很長時(shí)間，這意味著API決策需要徹底，團(tuán)隊(duì)也希望該API易于使用。

在API審核期間，會有人代表提案，并說明擬議設(shè)計(jì)的目標(biāo)和原因，然后，團(tuán)隊(duì)將對其進(jìn)行討論，并確定提案是否需要進(jìn)一步的工作，然后再批準(zhǔn)，在被認(rèn)為可以接受之前，可以在多次設(shè)計(jì)評審中提出一個(gè)API。

我真正欣賞團(tuán)隊(duì)的一點(diǎn)是，他們在YouTube上現(xiàn)場直播了這次會議，任何人都可以觀看，盡管有時(shí)在會議期間聊天中留下的評論和反饋可能被認(rèn)為是討論的一部分，但這主要是一種僅查看的方法，在YouTube上，.NET Foundation 頻道下的所有播放記錄都可以去瀏覽。

您可以在YouTube上查看HttpClient JSON擴(kuò)展方法的設(shè)計(jì)的討論，https://www.youtube.com/watch?v=_AHbjIS8_0I

當(dāng)我感興趣的API有討論的時(shí)候，我就會經(jīng)常上去看這些，我發(fā)現(xiàn)聽到討論并觀看.NET團(tuán)隊(duì)對設(shè)計(jì)框架的想法非常有趣，在此過程中必須考慮許多細(xì)微的差異，這里面包含了大量的.NET 方面的知識，通常會提出一些細(xì)微的實(shí)現(xiàn)細(xì)節(jié)行為，例如現(xiàn)有API的歷史方面及其行為，可能觀看這樣一次會議，要花一兩個(gè)小時(shí)， 但我還是建議您有空可以參加其中的一些會議，來真正欣賞.NET框架的設(shè)計(jì)。

在審查期間，通常會使用GitHub Issue的標(biāo)準(zhǔn)做法, .NET的程序經(jīng)理 Immo Landwerth 通常主持會議并在討論過程中做筆記, 任何關(guān)注,反饋和更改都將記錄為設(shè)計(jì)審查的輸出。

3. 提交階段 - PR

一旦獲得批準(zhǔn)，開發(fā)人員開始寫寫寫，來實(shí)現(xiàn)這個(gè)API，就像這個(gè)示例一樣，可能某些工作已經(jīng)試驗(yàn)完成，然后還將需要把一些更改的內(nèi)容，記錄到設(shè)計(jì)評審的反饋中。

該功能的大部分工作由David Cantu完成，可以在GitHub上的拉取請求（PR）這里看到，https://github.com/dotnet/runtime/pull/33459 ， 同樣的它在Github，公開透明，任何人都可以訂閱通知，甚至發(fā)表評論。

我建議開發(fā)人員應(yīng)該很熟悉這個(gè)階段，開發(fā)人員在git分支上完成了一些工作，一旦該工作完成并準(zhǔn)備好考慮合并，就可以創(chuàng)建一個(gè)PR，一般可以直接合并到項(xiàng)目，但是出于質(zhì)量考慮，其他開發(fā)人員通常會進(jìn)行一個(gè)或多個(gè)代碼審查，在Microsoft .NET世界中，這必須要考慮全面，因?yàn)椴灰恢潞托阅軉栴}可能是以后要解決的問題。

在這個(gè)例子中（Json擴(kuò)展庫），我們可以看到很多評論，包擴(kuò)多個(gè)有經(jīng)驗(yàn)的專家，您將看到有關(guān)代碼復(fù)雜性的詳細(xì)反饋，這是我從提出和討論的小項(xiàng)目中學(xué)到很多東西的地方，隨著時(shí)間的推移，您可以觀看PR，甚至可以查看較新的提交，這些提交可以解決反饋并解決任何問題。

4.合并發(fā)布 - Release

一旦所有的審閱者批準(zhǔn)了這個(gè)PR,然后這些代碼被合并到master分支中，因?yàn)?NET 運(yùn)行時(shí)是一個(gè)非常復(fù)雜的庫，里面有高級的構(gòu)建過程，來處理這些新合并的代碼。

最終，新代碼將出現(xiàn)在相關(guān)庫的夜間版本中(nightly)，也可能被推送到MyGet或NuGet feed中以供預(yù)覽使用和測試，對于本篇的示例，生成了一個(gè)新程序包，并在NuGet上作為預(yù)發(fā)布預(yù)覽發(fā)布了該程序包

總結(jié)

這個(gè)過程非常有趣，我們了解到了.NET 團(tuán)隊(duì)，最初由一個(gè)想法，再經(jīng)過設(shè)計(jì)，審查，討論，最終上線，這些都在Github進(jìn)行，都是公開的，在這個(gè)過程中，我們可以學(xué)習(xí)非常全面的.NET的知識，因?yàn)槲④浀膶＜姨幚磉@些事情，考慮的非常全面和細(xì)致。

最后

歡迎掃碼關(guān)注我們的公眾號 【全球技術(shù)精選】，專注國外優(yōu)秀博客的翻譯和開源項(xiàng)目分享，也可以添加QQ群 897216102

創(chuàng)作挑戰(zhàn)賽新人創(chuàng)作獎(jiǎng)勵(lì)來咯，堅(jiān)持創(chuàng)作打卡瓜分現(xiàn)金大獎(jiǎng)

總結(jié)

以上是生活随笔為你收集整理的探索 .NET团队对API的设计流程的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。