SuperAPI AI 工具集

dotnet-api-surface-validation

部署与运维

查看项目

更新于 10-16 01:27

技能介绍

用途:追踪并校验 .NET 库的公共 API 表面,在 CI 中拦截未声明或破坏性的 API 变更。按资料,版本基线为 .NET 8.0+,PublicApiAnalyzers 3.3+,ApiCompat 工具包含在 .NET 8+ SDK 中。资料明确将二进制/源兼容规则、NuGet 打包、多目标打包、Verify 基础、通用 Roslyn 分析器配置及 HTTP API 版本控制列为范围外。

主要能力:一是 PublicApiAnalyzers,通过提交到源码管理的文本文件追踪每个公共 API 成员,强制新 API 先经“unshipped”阶段再标记“shipped”。需安装 Microsoft.CodeAnalysis.PublicApiAnalyzers,并在项目根创建 PublicAPI.Shipped.txt 与 PublicAPI.Unshipped.txt,两文件均须存在且含 #nullable enable 头。相关诊断含 RS0016(API 未声明)、RS0017(已移除但文件仍存在)、RS0024、RS0025、RS0026、RS0036、RS0037。文件按文档注释 ID 格式书写,! 表示不可空引用类型,? 表示可空,属性展开为 .get/.set,构造器用类型名。发布时将 Unshipped 条目移入 Shipped 并清空 Unshipped。多 TFM 项目可设 RoslynPublicApiPerTfm 为 true 并按 TFM 提供文件。CI 中可将 RS0016 等加入 WarningsAsErrors 以拦截构建。二是 Verify 快照模式,用反射枚举程序集的全部公共类型与成员,生成提交到源码管理的快照,每次测试运行比对;任何公共 API 表面变化都会导致测试失败,直到显式批准。需为 Verify 提供公共 API 提取辅助方法与使用 [UsesVerify] 的测试类。失败时生成 .received.txt,可比对后用 verify accept 接受,或回退代码。三是 ApiCompat CI 强制执行,通过 EnablePackageValidation 与 PackageValidationBaselineVersion 在 dotnet pack 时校验;或安装 Microsoft.DotNet.ApiCompat.Tool 后用 apicompat --left-assembly ... --right-assembly ... 直接比较程序集。可在 PR 中加标签提示 API 变更。对有意破坏性变更,运行 dotnet pack /p:GenerateCompatibilitySuppressionFile=true 生成 CompatibilitySuppressions.xml,并以 ApiCompatSuppressionFile 作为 ItemGroup 项引用(用 PropertyGroup 语法会静默失效)。

限制:资料未提供具体价格、平台支持范围或效果保证;缺失信息暂未提供。