企业官网建设流程全解析

dotnet-skills是面向 .NET 开发者的开源 AI 编程技能库，内置 30 个生产级技能与 5 个专业智能体，覆盖 C# 编码标准、API 设计、包管理等场景。本文将系统解读其中extend-only API 设计哲学与NuGet 包版本兼容策略，帮你掌握设计稳定、可平滑升级公共 API 的关键方法。

📦 dotnet-skills：.NET AI 编程的"技能军火库"

dotnet-skills 把真实生产系统的经验沉淀为结构化的技能文档，供 Claude Code、Codex、GitHub Copilot 等 AI 助手按需调用：

每个技能是一个按类别组织的SKILL.md文件：skills/csharp-api-design/SKILL.md 讲公共 API 设计与兼容性，skills/package-management/SKILL.md 讲 NuGet 包管理。完整技能清单见 README.md。

🔍 如何选型：先搞懂 API 兼容性的三种类型

在谈 extend-only 之前，需要先理解 .NET 里"兼容性"的三层含义。技能文档 skills/csharp-api-design/SKILL.md#L20-L28 将其归纳为：

⚠️ 关键点：源码能编译 ≠ 二进制兼容。这是很多开发者踩坑的地方——例如给已有方法加一个可选参数会改变 IL 签名，旧调用方程序集在运行时会抛出MissingMethodException。详见 skills/csharp-api-design/SKILL.md#L104-L110。

🏛️ extend-only API 设计的三大支柱

extend-only 的核心思想只有一句话：永不删除或修改，只做扩展。文档 skills/csharp-api-design/SKILL.md#L32-L47 把它拆成三根支柱：

1. 既有功能不可变—— 一旦发布，行为与签名即被锁定
2. 新功能通过新构造物提供—— 加重载、加新类型、可选开启的特性
3. 删除必须经历弃用期—— 以"年"为单位，而不是以"版本"为单位

✅ 安全变更 vs 危险变更完整清单

💡 易错点：Process(Order order, CancellationToken ct = default)是典型的二进制不兼容改动——可选参数的默认值在编译期被固化进调用方程序集。正确做法永远是新增一个重载。

🕐 弃用三步走标准流程

技能文档推荐的标准弃用流程（参考 skills/csharp-api-design/SKILL.md#L116-L128）：

1. 第一步：给旧 API 打上[Obsolete]特性并写明替代方案
2. 第二步：同一版本内发布新推荐 API
3. 第三步：在下一个大版本（v2.0+）中才移除

同时，文档引用了切斯特顿篱笆原则：在删除或修改任何东西之前，先理解它为什么存在；假设每一个公共 API 都有人正在使用（参考 skills/csharp-api-design/SKILL.md#L311-L319）。

🚀 NuGet 包版本兼容策略：语义化版本实战指南

extend-only 如何落到 NuGet 版本号上？技能给出的语义化版本规则（参考 skills/csharp-api-design/SKILL.md#L294-L310）：

配套四条原则：不做意外破坏、扩展随时可发、先弃用后删除、公开变更时间线，让用户有充分的规划升级窗口。

🧪 API 审批测试：四步拦截破坏性变更

落地 extend-only 最实用的手段是API 审批测试（参考 skills/csharp-api-design/SKILL.md#L132-L174），用PublicApiGenerator+Verify.Xunit两个 NuGet 包给库的公共 API 面"拍照"存档：

1. 测试生成包含全部公共 API 的.verified.txt基线文件并提交到仓库
2. 任何 API 变更都会让测试失败
3. 审查者必须在 PR 中显式批准.verified.txt的 diff
4. 破坏性变更因此变得"肉眼可见"，必须经过有意识的人工决策

⚙️ 消费端：NuGet 版本管理的三个实用技巧

兼容策略不只属于库作者。dotnet-skills 的package-management技能在消费端同样提供了实用技巧（参考 skills/package-management/SKILL.md）：

1. 黄金法则：不要手改 XML—— 始终用dotnet add package等命令管理包，由 CLI 校验版本、处理传递依赖（参考 skills/package-management/SKILL.md#L19-L31）
2. 中央包管理（CPM）—— 把所有版本集中到解决方案根的Directory.Packages.props，消除多项目间的版本冲突（参考 skills/package-management/SKILL.md#L42-L89）
3. 共享版本变量—— 把 Akka.NET 家族等相关包绑定到同一个版本变量，改一处、全部对齐（参考 skills/package-management/SKILL.md#L93-L154）

🚀 快速上手：3 步安装 dotnet-skills

dotnet-skills 支持多种 AI 编码助手，几条命令即可装好。先克隆仓库：

git clone https://gitcode.com/gh_mirrors/do/dotnet-skills.git

然后把skills/目录复制到你的助手支持的技能目录——例如 GitHub Copilot 的项目级.github/skills/（推荐）或用户级全局目录（参考 README.md 的安装说明）。Claude Code 与 Codex 用户也可走 marketplace 一键安装，各助手的完整命令均收录在 README.md。

📋 总结：稳定 API 的 6 个要点

extend-only 不是复杂的技术，而是一种用短期便利换长期稳定的工程纪律。把 dotnet-skills 接入你的工作流后，AI 助手就能在每次写码、评审时自动遵循这套纪律，让版本兼容成为团队的默认习惯。