C#怎么进行API版本控制 ASP.NET Core API版本管理方法

ASP.NET Core API版本控制推荐使用Microsoft.AspNetCore.Mvc.Versioning包，通过URL路径、查询参数或请求头传递版本信息，并支持弃用标记与Swagger多版本文档。

ASP.NET Core 中做 API 版本控制，核心是让新旧版本共存、路由可区分、客户端能明确指定要调用哪个版本。不靠改 URL 后缀（比如 /api/v2/users）硬编码，而是用更规范、可扩展的方式——推荐用 URL 路径 + 查询参数 + 请求头 三者之一或组合，并配合官方 Microsoft.AspNetCore.Mvc.Versioning 包。

用 Microsoft.AspNetCore.Mvc.Versioning 包统一管理

这是微软生态最主流、维护良好的方案。安装 NuGet 包：

在 Program.cs（.NET 6+）中注册服务并启用版本控制：

关键配置说明：

• DefaultApiVersion：没带版本时默认走 v1.0
• AssumeDefaultVersionWhenUnspecified：允许不传版本也能访问（适合平滑过渡）
• ReportApiVersions：响应头里返回支持的版本列表（如 api-supported-versions: 1.0, 2.0）

三种常用版本定位方式（按推荐顺序）

版本信息可以从 URL、查询参数或请求头传入，框架自动识别：

• 路径版本（最直观）：GET /api/v1/users 或 GET /api/v2/users，控制器加特性：
  [ApiVersion("1.0")]
  [Route("api/v{version:apiVersion}/[controller]")]
• 查询参数版本（低侵入）：GET /api/users?api-version=2.0，需额外配置：
  options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
• 请求头版本（最干净）：GET /api/users + Header: api-version: 2.0，配置：
  options.ApiVersionReader = new HeaderApiVersionReader("api-version");

可以同时启用多种方式，框架会按顺序尝试匹配（默认：头 > 查询 > 路径）。

为不同版本写独立控制器或动作

推荐用命名空间或控制器名区分，避免一个控制器里堆满 if-else：

标签： 编码 路由 microsoft 微软 c# .net