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]，否则不会被识别为该版本入口。
处理弃用、迁移与文档一致性
版本不是只增不减。当 v1 不再维护，可标记为已弃用：
[ApiVersion("1.0", Deprecated = true)]这样响应头会多出
api-deprecated-versions: 1.0，方便客户端感知。搭配 Swagger 时，用
Swashbuckle.AspNetCore.Versioning.Swagger可自动生成多版本文档页，每个版本独立 UI。
另外，数据库兼容性、DTO 模型变更、中间件行为差异都要同步评估——版本控制只是入口，背后逻辑和契约才是重点。
基本上就这些。不复杂但容易忽略细节：比如忘了注册服务、没配
ApiVersionReader导致查询参数无效、或多个同名动作没加
[ApiVersion]而报错。用好官方包，版本管理就能清晰可控。
