.NET Web API 接口版本控制是构建可维护、可扩展的后端服务的重要环节。随着业务发展，API 需要不断迭代，但又要保证旧客户端不受影响。因此，合理地进行版本管理至关重要。以下是几种在 .NET 中实现接口版本控制的常见方案及具体实现方式。
1. URL 路径版本控制
这是最直观且广泛使用的方式，将版本号直接嵌入到 API 的 URL 路径中。
示例：
GET /api/v1/users GET /api/v2/users实现步骤（以 ASP.NET Core 为例）：
安装 NuGet 包：Microsoft.AspNetCore.Mvc.Versioning在
Program.cs或
Startup.cs中注册版本服务： builder.Services.AddApiVersioning(options =>
{
options.AssumeDefaultVersionWhenUnspecified = true;
options.DefaultApiVersion = new ApiVersion(1, 0);
options.ReportApiVersions = true;
});
builder.Services.AddVersionedApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
}); 在控制器上使用
[ApiVersion]特性并设置路由： [ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class UsersController : ControllerBase
{
[HttpGet]
public IActionResult Get() => Ok("v1 response");
}
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("2.0")]
public class UsersController : ControllerBase
{
[HttpGet]
public IActionResult Get() => Ok("v2 response with new fields");
}
通过这种方式，不同版本的控制器可以共存，框架会根据 URL 自动路由到对应版本。
2. 查询参数版本控制
将版本信息放在查询字符串中，适合不想改变 URL 结构的场景。
示例：
GET /api/users?api-version=1.0 GET /api/users?api-version=2.0配置与路径版本类似，只需在
AddApiVersioning中启用查询参数读取（默认已支持），然后通过
api-version参数传入版本号即可。
注意：该方式对 SEO 不友好，且不如路径清晰，建议内部系统或过渡期使用。
3. 请求头版本控制
通过自定义 HTTP 请求头传递版本信息，保持 URL 干净。
示例请求头：
Accept: application/vnd.myapp.v1+json或
Api-Version: 1.0要在 .NET 中支持基于 Accept 头的版本控制，需配置：
options.ApiVersionReader = new HeaderApiVersionReader("Api-Version");或使用媒体类型方式：
options.ApiVersionReader = ApiVersionReader.Combine( new MediaTypeApiVersionReader("v"), new HeaderApiVersionReader("X-Api-Version") );此方式更“RESTful”，但调试和测试稍复杂，需工具配合设置请求头。
4. 多版本共存与迁移策略
实际项目中，通常需要同时支持多个版本一段时间。建议：
为每个版本创建独立的控制器或使用[MapToApiVersion]标记特定 Action 通过 Swagger 配合
IApiVersionDescriptionProvider生成多版本文档 定期清理废弃版本，通知客户端升级 使用中间件记录旧版本调用，便于下线评估
例如，在 Swagger 配置中展示多个版本：
app.UseSwagger();app.UseSwaggerUI(options =>
{
var descriptions = app.DescribeApiVersions();
foreach (var desc in descriptions)
{
options.SwaggerEndpoint($"/swagger/{desc.GroupName}/swagger.json", desc.GroupName.ToUpperInvariant());
}
});
基本上就这些。选择哪种方式取决于团队规范、客户端兼容性要求和运维习惯。URL 路径版本最易理解，推荐大多数项目使用；Header 方式更适合成熟平台。关键是统一规则并长期坚持。
