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")] 显式绑定：
