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 包：

Install-Package Microsoft.AspNetCore.Mvc.Versioning

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

builder.Services.AddApiVersioning(options =>
  {
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
  });

关键配置说明：

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：

[ApiVersion("1.0")]
public class UsersController : ControllerBase { ... }

[ApiVersion("2.0")]
public class UsersControllerV2 : ControllerBase { ... }

或者用同一控制器、不同动作（带版本特性）：

[ApiVersion("1.0")]
[HttpGet]
public IActionResult Get() { ... }

[ApiVersion("2.0")]
[HttpGet]
public IActionResult Get() { ... } // 方法名可相同，因特性路由已区分

注意：必须给每个动作明确标注 [ApiVersion]，否则不会被识别为该版本入口。