在现代后端架构中，API 接口常常需要随着业务发展而不断演进。若不加控制地变更接口，很可能导致兼容性破坏、客户端错误或升级成本大幅上升。对于使用 .NET Core 构建 Web API 的开发者而言，理解并合理实现 API 版本控制（Versioning）至关重要。本文将从版本策略、实现方式、控制接口演进、弃用机制与工具集成等方面，全面讲解 .NET Core 下的 API 版本控制实践。
为何需要 API 版本控制
- 兼容性保障：当你需要新增、修改或删除 API 字段、行为或返回结构时，不破坏已有客户端调用成为核心需求。
- 渐进演进：能够并存多个版本，让旧客户端慢慢迁移，新功能优雅扩展。
- 弃用与退役路径：控制旧版本退出，让系统不断精简与优化。
- 文档与管理清晰：把版本信息清晰纳入文档与客户端协定之中，减少歧义与误用。
主流 API 版本策略
在 .NET Core 环境下，常见的版本控制策略包括：
URL 路径版本化（URI Versioning）
例如 /api/v1/products、/api/v2/products。优点是易识别、直观，但可能使 URI 臃肿。
Query 参数版本化
如 /api/products?api-version=1.0。保持路径清洁，但客户端调用需明确带版本参数。
HTTP 头部版本化（Header Versioning）
在请求头里传 X-API-Version: 1.0 或自定义版本头部。URL 干净，但实现稍复杂。
媒体类型版本化 / Content Negotiation
利用 Accept 或 Content-Type 中附带版本号（如 application/json;version=2）进行版本协商。这种方式最贴近 REST 的内容协商思想，但客户端与服务器实现更复杂。
每种策略有优有劣，常见做法是将几种方式结合使用，让 API 同时支持路径 + 头部或路径 + Query，以兼顾客户端灵活性。
在 .NET Core 中启用 API 版本控制
以下是实现版本控制的典型步骤：
1. 引入版本控制包
在项目中安装官方推荐的版本控制支持包，比如 Microsoft.AspNetCore.Mvc.Versioning 或社区版 Asp.Versioning 系列库。
2. 在启动配置中注册版本服务
在 Program.cs 或 Startup 中添加版本控制服务配置，例如：
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
// 可组合不同版本读取器（URL、头、Query 等）
options.ApiVersionReader = ApiVersionReader.Combine(
new UrlSegmentApiVersionReader(),
new HeaderApiVersionReader("X-Api-Version"),
new QueryStringApiVersionReader("api-version"));
})
.AddApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
});
这里 DefaultApiVersion 定义默认版本，ReportApiVersions 将向客户端暴露支持与弃用版本，SubstituteApiVersionInUrl 允许在路由模板里替换版本标记。
3. 在 Controller 或 Endpoint 上声明版本
在控制器或具体动作上标注版本信息：
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class ProductsController : ControllerBase
{
[HttpGet]
[MapToApiVersion("1.0")]
public IActionResult GetV1() => Ok(new { version = "v1" });
[HttpGet]
[MapToApiVersion("2.0")]
public IActionResult GetV2() => Ok(new { version = "v2", extra = "new field" });
}
或者对于 Minimal API，也可以创建 ApiVersionSet，然后通过 WithApiVersionSet 和 MapToApiVersion 将版本信息绑定到路由上。
4. 标记弃用版本
当某个版本需要逐步退役时，可以在 ApiVersion 注解中设置 Deprecated = true，让客户端在响应头中看到这一版本已弃用，同时继续提供兼容支持一段时间。
版本演进与服务层设计思路
单纯版本化控制入口并不足够，还需在服务层（Service / 业务逻辑）做合理拆分：
- 不要直接在服务层命名版本（如 UserServiceV2），除非业务逻辑完全不同。更推荐让 Controller 层对不同版本调用不同参数或策略，然后复用服务层核心逻辑。
- 对于真正发生重大变更的业务，可以采用策略模式、适配器或版本适配层，将新的版本逻辑与旧版本隔离。
- 在内部接口或 DTO 里，使用版本友好的数据模型，尽量保证向后兼容性或给出默认值。
在社区讨论中，有人建议：
- 你的控制器处理版本路由，而业务层逻辑只保留一种实现，控制器根据版本调用不同参数或适配逻辑。
- 对服务层版本命名要谨慎，避免无限扩张版本号命名。
版本控制与文档 / Swagger 集成
良好的 API 版本控制应与文档系统（如 Swagger / OpenAPI）结合，让不同版本的接口在文档里清晰展现：
- 使用 Asp.Versioning.Mvc.ApiExplorer（或相关扩展包）将版本控制器与 API Explorer 整合，使 Swagger 能显示多个版本文档。
- 在 Swagger UI 中展示版本选择器，让客户端可以切换版本查看。
- 对弃用版本在文档中标注为 deprecated，并提供迁移建议。
- 为每个版本编写清晰的接口说明、变更日志与迁移指南。
- 在 .NET 8 环境下，如果你使用 AddApiExplorer，还需注意版本描述提供者（如 IApiVersionDescriptionProvider）的正确配置，否则可能导致某些版本在 Swagger 中不可见。
常见挑战与实践建议
- 参数与响应兼容性处理：尽量避免在新版本中直接删除字段或改变语义，如果必须更改，应设计默认值或兼容分支。
- 版本爆炸管理：不要为每个小改动都创建版本。有效的版本策略应限定主要变更时才升级版本号。
- 弃用周期规划：在版本发布之初就设定弃用时间表，并通过 HTTP 头、文档等渠道提前告知客户端。
- 回滚与错误处理：在某个新版本出现问题时，应有机制快速回退到稳定版本，并兼顾旧版本用户请求。
- 路由冲突与优先级：多个版本共存时，路由设计要避免冲突。版本替换、路由优先级设置及 SubstituteApiVersionInUrl 等选项应谨慎配置。
- 测试覆盖不同版本：单元测试、集成测试要覆盖各版本接口，确保在版本转换、并存期间行为一致。
总结
在 .NET Core / ASP.NET Core 应用中，API 版本控制不仅是一种推荐做法，更是保持系统演进与兼容并存的核心机制。通过合理选择版本策略（URL、Query、Header、媒体类型混合），在启动时注册版本服务，在 Controller / Minimal API 上声明版本，设计清晰的服务层适配逻辑，整合 Swagger 文档系统，以及控制弃用周期与测试覆盖，你能打造一个既灵活又可靠、长期可维护的 API 平台。