探索 .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