用 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<IApiVersionDescriptionProvider>();
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 接口依然照常工作——这点容易被忽略，导致技术债越积越多。
