0Pricing
C# Academy · 课时

API 版本控制策略

通过 URL、标头和查询字符串指定版本。

API 版本控制策略 是 CoddyKit 上的免费 C# Academy 课时。 这是第 1 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 C# Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 C# Academy 课程共包含 4 节课。

为什么要对应用程序接口进行版本控制

一旦客户端依赖您的应用程序接口，您就不能破坏其契约。版本控制让您可以在新版本中发布破坏性变更，同时让旧客户端继续使用旧版本。

// v1 returns { name }
// v2 returns { firstName, lastName }  (breaking)

URL 路径版本控制

最直观的策略是将版本放在路径中。这种方式含义明确，便于路由、浏览和缓存。

GET /api/v1/products
GET /api/v2/products

查询字符串版本控制

版本作为查询参数传递。URL 保持稳定，并且可以在缺少参数时默认使用最新版本或固定版本。

GET /api/products?api-version=1.0
GET /api/products?api-version=2.0

标头版本控制

自定义请求标头携带版本，从而保持 URL 简洁。缺点是它不会显示在浏览器地址栏中，手动测试也更困难。

GET /api/products
X-Api-Version: 2.0

媒体类型版本控制

这种方式也称为内容协商。版本嵌入 Accept 标头的媒体类型中。它最符合 REST 风格，但也是最不易发现的选项。

GET /api/products
Accept: application/json;v=2.0

比较这些策略

每种策略都需要在可发现性和 URL 简洁性之间进行权衡：

  • URL 路径：最容易发现，但会使 URL 变得杂乱。
  • 查询字符串：URL 稳定，默认值易于设置。
  • 标头：URL 简洁，但浏览器不可见。
  • 媒体类型：最纯粹地遵循 REST，但最难使用。
// Many teams pick URL path for public APIs

应用程序接口的语义化版本控制

应用程序接口版本通常只使用主版本（v1、v2）。请将次版本留给向后兼容的增量变更，以便旧客户端忽略这些变更。

// v1.0 -> v1.1 : additive (safe)
// v1   -> v2   : breaking (new version)

弃用

永远不要突然移除旧版本。请将其标记为已弃用，公布停止服务日期，并通过标头向客户端发出信号。

// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: true

默认版本

请决定客户端未发送版本时应如何处理。常见选择包括：假定使用最新版本、假定使用 v1，或拒绝请求。明确规定可以避免意外情况。

// Strategy: unversioned request -> treat as v1.0

为正确的内容进行版本控制

请为契约（路由、请求/响应结构）进行版本控制，而不是为内部实现细节进行版本控制。v2 终结点可以与 v1 共享大部分业务逻辑。

// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller

混合使用多种策略

ASP.NET Core 的版本控制库可以同时从多个来源读取版本，让客户端选择最方便的方式。下一步将对此进行配置。

// Accept version from URL OR header OR query

快速检查

测试您对版本控制策略的理解。

回顾

您了解了应用程序接口版本控制策略：

  • URL 路径、查询字符串、标头和媒体类型。
  • 每种策略都需要在可发现性和 URL 简洁性之间进行权衡。
  • 为契约进行版本控制，平稳地弃用旧版本，并定义默认版本。

下一部分：在 ASP.NET Core 中配置 Asp.Versioning。

常见问题解答

「API 版本控制策略」课时是免费的吗？

是的 — 「API 版本控制策略」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 C# Academy 课程的其余内容，请升级到 CoddyKit PRO。 C# Academy 课程共包含 4 节课。

「API 版本控制策略」这节课中我会学到什么？

通过 URL、标头和查询字符串指定版本。 你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 C# Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 C# Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。

「API 版本控制策略」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 C# Academy 课中编写并运行代码吗？

能。每节 C# Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. API 版本控制策略
  2. 配置 Asp.Versioning
  3. 生成 OpenAPI 文档
  4. 记录有版本的 API
← 返回 C# Academy