用途:为 NuGet 包或类库设计稳定的公共 API,并在修改现有 API、规划分布式系统线格式变更、制定版本策略或审查破坏性变更 PR 时使用。
主要能力:区分 API/源码、二进制、线格式三类兼容性;给出仅扩展式设计三原则(已发布行为不可变、通过新构造添加功能、仅在弃用期后移除);提供类型与方法命名约定(I 前缀、Async 后缀、Is/Has/Can、Try 模式、Create/To/From 等),并建议公共 API 避免缩写;规定参数顺序(目标、必填、可选、CancellationToken 最后,CA1068)与重载递进;给出返回类型选择表(可空、IReadOnlyList、IAsyncEnumerable、Result、ValueTask 等);说明异常层次、Try 模式与参数校验;列出安全变更与不安全变更清单、[Obsolete] 弃用流程、扩展点与扩展方法准则;线格式部分要求读写双向兼容,采用先加读侧支持、再开启写侧的分阶段演进,并建议枚举用字符串序列化、避免多态类型名;最后用 API 审批测试(PublicApiGenerator + Verify)在 PR 中暴露 API 表面变化,并给出语义化版本与 PR 检查清单。
使用方式:资料未提供安装命令或具体调用步骤,仅给出示例代码片段(如 ArgumentException.ThrowIfNullOrWhiteSpace、[JsonConverter(typeof(JsonStringEnumConverter))]、akka.cluster.use-heartbeat-v2 = on 等),需按原文保留。
适用场景:类库公共 API 设计、版本升级与弃用规划、分布式消息格式演进、PR 破坏性变更审查。
限制:资料未说明支持的 .NET 版本、工具依赖、收费或平台信息;示例中的 Akka 配置与测试框架仅为示例,未提供完整集成步骤。