ASP.NET Core 开源仓库 API 评审流程全指南从提案到api-approved的完整实战【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore导读在 dotnet/aspnetcore 仓库中任何对**公共 APIPublic API**的增改都不是随实现 PR 一并完成的而是通过一套独立的API Proposal IssueAPI 提案 Issue机制进行专门评审。本文以仓库官方文档 docs/APIReviewProcess.md 为主线结合仓库内实际配套的api-reviewSkill.github/skills/api-review/SKILL.md、API 基线文件规范docs/APIBaselines.md以及真实的PublicAPI.Unshipped.txt基线文件如 src/Http/Http/src/PublicAPI.Unshipped.txt为你完整还原一条 API 从被识别、被提案、被评审到最终进入 RTM 发布的全链路。读完本文你将掌握API 提案 Issue 与实现 PR 的正确拆分方式、四个核心标签api-suggestion/api-proposal/api-ready-for-review/api-approved的流转时机、ref-assembly 格式的撰写规范、如何借助api-reviewSkill 自动起草提案以及如何在每周 API Review 会议中为自己的变更辩护。为什么需要独立的 API 评审流程在 ASP.NET Core 仓库中API 评审API Review的目标是确保新 API 遵循通用模式和最佳实践帮助和引导工程师做出更好的 API 设计决策。它不仅是质量门禁更是一个学习与知识共享的过程——工程师应当乐于提交自己的 API 接受评审因为除了流程本身带来的收益这也是积累设计经验的机会。API 变更在与跟踪功能或实现的 Issue 相互独立的 API 提案 Issue中评审。核心思想是实现工作与 API 形状的裁决解耦。当打开一个新增或修改公共 API 的实现 PR 时文档要求使用api-reviewSkill 从原始 Issue 和 PR 出发创建提案 Issue。端到端流程全景整个流程可以用下面的流程图直观呈现摘自 docs/APIReviewProcess.md分步拆解8 个关键节点识别 API 变更当 Issue 负责人确认该 Issue 的工作需要 API 变更或新增时评审流程正式启动。此时负责人将亲自或与有意承接该工作的社区成员一起推动设计提案。与社区成员合作时负责人有责任引导其走向可接受的设计。实现可先于评审API 评审可能发生在实现之前、之中或之后。贡献者可以先实现 API、打开或标记 PR 为 ready甚至在提案获得api-approved之前就合并工作。这是一条重要且容易误解的规则PR 就绪与合并并不以api-approved为前提。使用api-reviewSkill 提交独立提案当打开新增或修改公共 API 的实现 PR 时使用api-reviewSkill 提交独立的 API 提案 Issue。提案 Issue必须链接到原始 Issue 和实现 PR并同时使用api-suggestion与api-proposal两个标签。标记评审就绪当 Issue 负责人认为提案已成型即为 Issue 打上api-ready-for-review标签并通知dotnet/aspnet-api-review团队。参加评审会议aspnet-api-review团队每周举办 API 评审会议将在下一次会议上评审你的 API 变更。如果 API 被排期评审你必须派代表参会。所有待评审提案清单可在 aka.ms/aspnet/apireviews 查看。快速通道部分 API 评审可通过更短的流程完成只需直接联系 API 评审成员以对话形式快速完成评审。打上api-approvedAPI 变更/建议获得批准后应为 Issue 添加api-approved标签。Issue 负责人有责任确保该标签覆盖最终实现形态的 API之后该 API 才可进入 RTM 发布。形状变更需回炉如果实现改变了提案中或此前已批准的 API 形状必须更新提案并在该 API 进入 RTM 发布前将修订后的形状重新提交评审。同样合并后还需核对已批准的提案是否与最终实现一致——不一致则回到提案环节一致则验证标签后放行 RTM。四个核心标签一张表看懂流转标签作用添加时机api-suggestion标识这是一个 API 建议创建提案 Issue 时与api-proposal一起添加api-proposal标识这是一个正式提案创建提案 Issue 时与api-suggestion一起添加api-ready-for-review标识提案已准备好进入评审提案内容成型、Issue 负责人确认后api-approved标识 API 已获批准评审会议通过后且须覆盖最终实现形状值得注意的是在实现 PR 合并后仍存在一道校验已批准的提案是否与最终实现一致流程图中final判断。若实现过程中 API 形状发生漂移提案必须更新并回到评审否则不能进入 RTM。借助api-reviewSkill 起草高质量提案仓库中提供了官方 Skill.github/skills/api-review/SKILL.md用于从原始 Issue 与实现变更自动起草并提交独立的 API 提案 Issue。它明确声明适用于撰写 API 评审 Issue、准备 api-ready-for-review 提案、填充 API 提案模板不适用于评审 API 设计决策、批准 API、实现 API 或一般代码评审。Skill 的工作流收集证据读取原始 Issue 及其全部评论检查实现 PR、提交与 diff确保每一个变更的 public/protected 类型、成员、签名、默认值或约定都被覆盖。起草提案按 issue-template.md 的章节模板逐节填充——其中Background and Motivation、Usage Examples、Proposed API 为必填Alternative Designs 与 Risks 为可选若证据不足须向用户逐个提问只有用户确认没有时才写N/A。补充来源引用在 Issue 末尾将每一条实质性论断映射到原始 Issue 或实现变更的原文引用。自检清单包括背景是否让非本领域评审者也能理解完整 API 提案是否为 ref-assembly diff 格式是否链接了原始 Issue 与 PR大变更是否有成比例的说明使用示例是否展示预期消费方式等。创建独立 Issue标题以[API Proposal]为前缀正文填充完毕添加api-suggestion与api-proposal标签。回链 PR将提案 Issue 链接添加到实现 PR 中且不得删除 PR 原有描述。提案 Issue 的章节模板要点仓库中的模板文件 .github/skills/api-review/assets/issue-template.md 定义了五大章节Background and Motivation描述新 API 的目的与价值Usage Examples给出代码示例展示提案 API 如何被消费有助于判断 API 形状是否功能完善、性能良好、易于使用Proposed API给出具体的公共 API 签名 diffAlternative Designs可选是否考虑过其他方案如其他 API 形状与其它生态/库中类似 API 的比较Risks可选如破坏性变更、性能回退等风险。章节撰写指南精华配套的 section-guidelines.md 给出了非常具体的写作标准Background and Motivation要聚焦为什么需要而非如何实现并链接原始 Issue 与实现 PR。好例解释用户此前只能通过InvokeAsync包裹 JS 函数带来的样板代码痛点坏例Adding a string overload for Widget.ConfigureFactory.一句空泛的标题式描述。Proposed API必须使用ref-assembly 格式包含完整命名空间与类型声明新增用前缀、移除用-前缀覆盖所有重载与扩展方法可参考PublicAPI.Unshipped.txt的变化但应重建为完整的 ref-assembly 声明而非粘贴孤立的基线条目。Alternative Designs应描述其他 API 形状、比较类似 API、说明取舍与最终选择理由。Risks需考虑破坏性变更、性能影响、安全、兼容性、潜在误用及对既有模式的影响。让 Issue/PR 达到 ready-for-review 的标准在标记api-ready-for-review之前务必确保 Issue 具备以下内容一段简短描述帮助不熟悉该领域的评审者快速理解背景ref-assembly 格式的 API 变更——可以直接链接 PR 中生成的 ref-assembly 代码如果变更所在区域不产出 ref-assembly则需手动写出其在 ref-assembly 格式下的样子供评审。原文档给出了一组示例值得反复品味Good: This is the API for the widget factory, users use it in startup code to configure how their widgets work. We have an overload that accepts URI, but not one that accepts string, so were adding it for convenience. Bad: Adding a string overload for Widget.ConfigureFactory.关于 Issue 顶楼评论的编辑规则理想情况下以上信息都应放在 Issue 的顶楼评论但当 Issue 由用户打开时并不总是可行。规则是不随意编辑或替换用户评论格式修正或违规处理除外。此时可以在 Issue 上发布新评论或在顶楼插入链接若编辑外部贡献者的帖子以添加链接必须说明原因。一个实用的经验法则变更越大需要提供的说明与上下文越多小型变更说明可少大型变更或功能级设计应附带大量上下文说明。为什么必须这样做把这些信息连同上下文写进 Issue可以在 API 评审会议之前就展开讨论。将设计写下来并发布到线上既支持远程协作也让社区有机会对设计给出反馈。其核心诉求是为工作在该功能领域之外的人提供足够的上下文使其能理解变更并给出有意义的反馈——如果你准备在会上展示一项变更就应该能解释它为何重要。为什么偏偏用 ref-assembly 格式仓库文档给出了明确答案ref-assembly 格式更易读、更适合 API 评审讨论中出现的各种问题。使用更紧凑的格式去掉文档与实现细节能让评审者更容易注意到 API 的模式与形态。在极少数需要手动誊写该格式的情况下可以理解为你花一点点时间为会议中的许多人节省大量时间。ref-assembly 格式的 diff 示例来自 skill 配套指南namespace Microsoft.AspNetCore.Http; public static class HttpResponseWritingExtensions { public Task WriteAsync(this HttpResponse response, StringBuilder builder); }复杂场景涉及接口扩展的示例namespace Microsoft.JSInterop { public interface IJSRuntime { ValueTaskTValue GetValueAsyncTValue(string identifier); ValueTaskTValue GetValueAsyncTValue(string identifier, CancellationToken cancellationToken); ValueTask SetValueAsyncTValue(string identifier, TValue value); ValueTask SetValueAsyncTValue(string identifier, TValue value, CancellationToken cancellationToken); } }API 基线文件与PublicAPI.Unshipped.txt的配合API 评审与仓库的API 基线API Baselines机制紧密配合。详见 docs/APIBaselines.mdPublicAPI.Shipped.txt记录上一个主版本已发布的 API。该文件只应在主版本发布后由构建团队修改平时严禁改动PublicAPI.Unshipped.txt记录自上一个主版本以来的新 API。新增 API、移除 API*REMOVED*前缀、更新 API同时移除旧签名并添加新签名包括可空性感知的更新都要在此登记。实际例子可以在仓库中找到例如 src/Http/Http/src/PublicAPI.Unshipped.txt。其典型条目格式如下来自 APIBaselines 文档#nullable enable Microsoft.AspNetCore.Builder.NewApplicationBuilder.New() - Microsoft.AspNetCore.Builder.IApplicationBuilder!#nullable enable *REMOVED*Microsoft.AspNetCore.DataProtection.Infrastructure.IApplicationDiscriminator.Discriminator.get - string! Microsoft.AspNetCore.DataProtection.Infrastructure.IApplicationDiscriminator.Discriminator.get - string?需要特别强调的是这也是api-reviewSkill 的规则之一PublicAPI.Unshipped.txt只追踪兼容性并不代表 API 获得批准。批准权完全掌握在 API 评审流程手中基线文件是评审的输入材料而非结论。日常维护基线文件的操作路径摘录自 APIBaselines 文档新项目需手动添加基线文件可从eng/PublicAPI.empty.txt复制修改 API 后通过构建错误如 RS0016触发快速修复选择Add Blah to public API对无法修复的常见错误建议使用特性attribute而非全局或#pragma抑制例如[SuppressMessage(ApiDesign, RS0026:..., Justification Required to maintain compatibility)]使抑制理由显式化。如果你是社区变更的 champion如果你被指派为某项社区提交的变更在 API 评审中的champion倡导者/代言人文档的表述颇具人情味穿上你的睡衣假装这个变更一开始就是你自己的put on your pretend pajamas and pretend that it was your change to begin with。在会议中你要准备好解释为什么需要这个新增以及为什么这是最佳方案。结合api-reviewSkill 的自检清单champion 还需要在提案中明确被识别出来以便评审会议有明确的对接人。API Review 会议机制与出席要求API 评审会议对 ASP.NET Core 团队所有成员开放会议邀请及 API 评审相关沟通通过内部ASP.NET Core API Reviews分发列表共享。每次评审会议都应包含 API 变更提案的area owners领域负责人作为必须出席的与会者。领域负责人的完整映射表见 docs/area-owners.md例如area-auth、area-blazor、area-mvc、area-minimal、area-signalr等各自对应不同的 Owners 与 Doc Owners。所有待评审 API 提案的清单可在 aka.ms/aspnet/apireviews 查阅。出席是硬性要求如果你的 API 被排期评审必须派代表参会否则评审无法有效推进。原则沉淀与知识传承随着时间的推移团队会积累某些约定与原则这些对未来 API 评审同样有用。为此docs/APIReviewPrinciples.md 文档被用于沉淀这些原则与约定使其长期留存最终成长为一份良好的知识库帮助新人更好地准备和设计他们的 API。评审中形成的通用设计原则还可参考 .NET 框架设计指南.NET Framework Design Guidelines作为非仓库特定的一般性指导。结语ASP.NET Core 的 API 评审流程是一套实现自由、批准严格的机制实现与 PR 合并不受评审阻塞但任何进入 RTM 的公共 API 都必须经过独立的提案评审并最终被api-approved覆盖。掌握这套流程不仅能让你的贡献顺利合入更能借助api-reviewSkill、ref-assembly 格式与每周评审会议提升自身 API 设计的专业水准。下一次当你准备向 aspnetcore 仓库提交公共 API 变更时记得从创建独立的[API Proposal]Issue 开始。【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考