Microsoft.AspNetCore.Mvc.Versioning 是 ASP.NET Core 官方推荐的最稳妥版本控制方案，支持路径（/api/v1/users）、查询参数（?api-version=1.0）和请求头等多种方式，自动返回 400/406 错误，并需配合 UrlSegmentApiVersionReader、[ApiVersion] 与 [Route("api/v{version:apiVersion}/[controller]")] 成对使用，同时通过 IApiVersionDescriptionProvider 获取元数据以支撑 Swagger 多版本文档及运行时校验。
用 Microsoft.AspNetCore.Mvc.Versioning 做路由+查询参数版本控制最稳妥
这是目前 ASP.NET Core 官方推荐、社区最成熟的方案，支持 URL 路径（/api/v1/users）、查询参数（/api/users?api-version=1.0）、请求头（api-version: 1.0）等多种方式，且能自动返回 400 Bad Request 或 406 Not Acceptable 提示缺失/不支持的版本。
安装 NuGet 包：Microsoft.AspNetCore.Mvc.Versioning（注意不是过时的 Microsoft.AspNet.WebApi.Versioning）。
在 Program.cs 中注册服务：
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
options.ApiVersionReader = new UrlSegmentApiVersionReader(); // 支持 /v1/ 路由
});
关键点：
-
UrlSegmentApiVersionReader启用路径段版本（如/api/v1/users），需配合路由模板使用 -
QueryStringApiVersionReader启用?api-version=1.0，可与前者共存 -
AssumeDefaultVersionWhenUnspecified = true表示没传版本时默认走DefaultApiVersion，否则会直接 400 -
ReportApiVersions = true会在响应头加api-supported-versions和api-deprecated-versions
[ApiVersion] 和 [MapToApiVersion] 必须成对使用才能路由到正确 Controller
只加 [ApiVersion("1.0")] 不够，ASP.NET Core 不会自动把 /v1/users 映射到带该特性的 Controller —— 你还得显式告诉路由系统“这个 Controller 只响应 v1”。
正确写法是：在 Controller 上同时标注 [ApiVersion] 和 [Route]，并确保路由模板含版本段（如 v{version:apiVersion}）：
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiController]
public class UsersController : ControllerBase
{
[HttpGet] public IActionResult Get() => Ok("v1");
}
如果想让同一 Controller 支持多个版本（比如 v1 和 v2 接口逻辑一致），可以叠加多个 [ApiVersion]：
[ApiVersion("1.0")]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class UsersController : ControllerBase { ... }
但更常见的是拆成不同 Controller，用 [MapToApiVersion("2.0")] 显式绑定：
[ApiVersion("2.0")]
[MapToApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class UsersControllerV2 : ControllerBase { ... }
否则会出现「请求 /v2/users 却进了 v1 Controller」或「404」—— 因为路由引擎没被告知哪个 Controller 对应哪个版本。
升级到 v3+ 时 IApiVersionDescriptionProvider 是获取所有版本元数据的唯一入口
生成 Swagger 文档、构建版本切换 UI、做运行时版本校验时，不能靠硬编码或反射 Controller 列表。必须通过 DI 获取 IApiVersionDescriptionProvider 实例：
var provider = app.Services.GetRequiredService(); foreach (var description in provider.ApiVersionDescriptions) { Console.WriteLine($"Version: {description.ApiVersion}, IsDeprecated: {description.IsDeprecated}"); }
这个对象在 AddApiVersioning() 后自动注册，包含全部已注册的 API 版本、是否弃用、是否稳定等信息。漏掉这步，Swagger 就只能显示默认版本，或者根本无法区分 v1/v2 的文档分组。
常见错误：
- 手动拼接
/v1/路由但没配UrlSegmentApiVersionReader→ 请求 404 - Controller 有
[ApiVersion]但路由没写v{version:apiVersion}→ 版本匹配失效 - 启用
ReportApiVersions但前端没读响应头 → 无法自动发现可用版本 - Swagger 配合
Swashbuckle.AspNetCore时，没调用options.SwaggerDoc(...)为每个版本单独注册 → 文档混在一起或丢失
弃用旧版本时 [ApiVersion("1.0", Deprecated = true)] 不会自动拦截请求
标记 Deprecated = true 只影响文档生成（Swagger 会加删除线）和响应头（api-deprecated-versions），不会阻止客户端调用。真正要停用 v1，必须配合 IApiVersionSelector 自定义策略，或在中间件里检查 HttpContext.GetRequestedApiVersion() 并返回 501 Not Implemented。
例如，在 Program.cs 注册自定义选择器：
options.ApiVersionSelector = new CurrentImplementationApiVersionSelector(options);
然后继承 IApiVersionSelector，在 SelectVersion 方法中判断版本是否已下线。否则，哪怕你标了 Deprecated = true，v1 接口依然照常工作——这点容易被忽略，导致技术债越积越多。
