推荐使用 microsoft.aspnetcore.mvc.versioning 包实现 asp.net core api 版本控制，支持 url、查询参数、请求头等多种版本标识方式，需在 program.cs 中注册服务并配置默认版本、弃用提示等，控制器通过 [apiversion] 特性声明版本支持。
ASP.NET Core 实现 API 版本控制，推荐使用官方支持的 Microsoft.AspNetCore.Mvc.Versioning 包，它轻量、灵活，与 MVC 深度集成，支持 URL、查询参数、请求头等多种版本标识方式。
安装并启用版本控制服务
在 Program.cs 中注册服务并配置基础行为：
- 通过
AddApiVersioning启用版本控制，设置默认版本（如1.0）和是否报告支持的版本 - 可选启用
AssumeDefaultVersionWhenUnspecified = true，让无版本请求默认走 v1 - 若需返回
api-supported-versions或api-deprecated-versions响应头，开启ReportApiVersions = true
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
});
在控制器中声明版本支持
使用 [ApiVersion] 特性标注控制器或具体 Action，支持多个版本同时存在：
- 单个控制器支持多版本：加多个
[ApiVersion("1.0")]和[ApiVersion("2.0")] - 不同控制器处理不同版本：如
ProductsControllerV1和ProductsControllerV2，都路由到/api/products - 配合
[MapToApiVersion("2.0")]可将某个 Action 限定只响应 v2 请求
选择版本识别方式（URL / Query / Header）
默认通过请求头 api-version 识别，但更常见的是 URL 路径（如 /api/v1/products）或查询参数（如 /api/products?api-version=1.0）：
-
URL 路径：配置
options.ApiVersionReader = new UrlSegmentApiVersionReader();，再用[Route("api/v{version:apiVersion}/[controller]")] -
查询参数：用
new QueryStringApiVersionReader("api-version") -
请求头：默认即支持，客户端传
api-version: 2.0 - 也可组合使用，如优先读 URL，降级读 Header
处理弃用与兼容性提示
对已废弃的版本，可通过特性明确标记，并由框架自动注入响应头：
- 给控制器加
[ApiVersion("1.0", Deprecated = true)] - 启用
ReportApiVersions = true后，v1 接口响应头会包含api-deprecated-versions: 1.0 - 客户端可根据该头决定是否提醒用户升级，服务端无需手动拦截或返回特殊状态码
基本上就这些。不复杂但容易忽略细节，比如忘了注册服务、没配路由模板、或多个版本控制器冲突——调试时留意日志里 ApiVersionMatcherPolicy 的匹配结果即可。
